@flytedesk/app-kit 3.2.2 → 4.0.0

package/dist/auth/plugin.js

@@ -1,14 +1,51 @@
 import { randomUUID } from "node:crypto";
 import fp from "fastify-plugin";
 import fastifyCookie from "@fastify/cookie";
-import { AuthStoreError, IdpAccessRevokedError, classifyIdpError } from "./errors.js";
+import { AuthStoreError, IdpAccessRevokedError, IdpUnavailableError, classifyIdpError, } from "./errors.js";
 import { createOidcClient } from "./oidc-client.js";
 import { generatePkce, randomState } from "./pkce.js";
-import { AUTH_REQUEST_DEADLINE_MS, AUTH_ROUTE_PREFIX, authRoutePath, SILENT_AUTH_MESSAGE_SOURCE, SIGNIN_ERROR_QUERY_PARAM, } from "./shared-types.js";
-import { generateRefreshToken, hashRefreshToken, signAccessToken, verifyAccessToken } from "./tokens.js";
+import { AUTH_REQUEST_DEADLINE_MS, AUTH_ROUTE_PREFIX, authRoutePath, SIGNIN_ERROR_QUERY_PARAM, } from "./shared-types.js";
+import { requireAuth } from "./guards.js";
+import { renderSilentAuthPage } from "./silentAuthPage.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;
+/**
+ * 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
+ * failure or a verdict by type alone, and never mistakes one for "not found".
+ */
+async function storeCall(method, call) {
+    try {
+        return await call();
+    }
+    catch (err) {
+        throw new AuthStoreError(`AuthStore.${method} failed`, err);
+    }
+}
+/** A plain decimal numeral: what a token endpoint that serializes numbers as strings sends. */
+const DECIMAL_NUMERAL = /^\d+(?:\.\d+)?$/;
+/**
+ * A `/token` response's `expires_in` as seconds, or `null` when it is unusable (AK-23).
+ * RFC 6749 §5.1 makes it a number, but a numeric string (`"3600"`) is accepted, as 3.x's
+ * implicit coercion did. Anything else — a non-numeral string, zero, a negative or
+ * non-finite number, a missing value — is `null`, never NaN.
+ */
+function parseExpiresInSeconds(value) {
+    const seconds = typeof value === "string" && DECIMAL_NUMERAL.test(value) ? Number(value) : value;
+    return typeof seconds === "number" && Number.isFinite(seconds) && seconds > 0 ? seconds : null;
+}
+/** When an IdP access token from `tokens` expires. An unusable `expires_in` makes it
+ *  "already expired" — the next request refreshes it — never an Invalid Date a store
+ *  would reject. Cannot throw. */
+function idpAccessTokenExpiresAt(tokens) {
+    return new Date(Date.now() + (parseExpiresInSeconds(tokens.expires_in) ?? 0) * 1000);
+}
+function unavailableCodeFor(err) {
+    return err instanceof AuthStoreError ? "auth_store_unavailable" : "idp_unavailable";
+}
 const REQUIRED_STRING_OPTIONS = [
     "clientId",
     "clientSecret",
@@ -26,6 +63,10 @@ function assertRequiredOptions(options) {
             throw new Error(`@flytedesk/app-kit/auth: missing required option "${key}"`);
         }
     }
+    if (Buffer.byteLength(options.accessTokenSecret, "utf8") < MIN_ACCESS_TOKEN_SECRET_BYTES) {
+        throw new Error(`@flytedesk/app-kit/auth: "accessTokenSecret" must be at least ${MIN_ACCESS_TOKEN_SECRET_BYTES} bytes — ` +
+            "it signs access tokens and keys refresh-token rotation; generate it randomly (e.g. openssl rand -base64 48)");
+    }
     if (options.cookieSecret == null ||
         (Array.isArray(options.cookieSecret) ? options.cookieSecret.length === 0 : options.cookieSecret.length === 0)) {
         throw new Error('@flytedesk/app-kit/auth: missing required option "cookieSecret"');
@@ -53,6 +94,8 @@ const flytedeskAuthPlugin = async (fastify, options) => {
     // interactive flow to land anywhere sensible.
     const silentAuthTargetOrigin = new URL(options.postLoginRedirect).origin;
     const store = options.store;
+    // The key refresh-token rotation derives successors with (see successorRefreshToken).
+    const successorKey = refreshSuccessorKey(options.accessTokenSecret);
     if (options.authorizationCacheTtlMs) {
         fastify.log.warn({ authorizationCacheTtlMs: options.authorizationCacheTtlMs }, "@flytedesk/app-kit/auth: authorizationCacheTtlMs is set — flytedesk-id authorization " +
             "checks will be cached instead of live. A role/permission revoked in flytedesk-id can " +
@@ -68,6 +111,7 @@ const flytedeskAuthPlugin = async (fastify, options) => {
     });
     await fastify.register(fastifyCookie, { secret: options.cookieSecret });
     fastify.decorateRequest("authUser", undefined);
+    fastify.decorateRequest("authUnavailable", undefined);
     // __Host- requires Secure, no Domain attribute, and Path=/ — so the prefix (and the
     // Path=/ it forces) is only used when options.secureCookies says this is actually an
     // HTTPS deployment. Plain, scoped cookies are used for local HTTP dev, where __Host-
@@ -96,80 +140,121 @@ const flytedeskAuthPlugin = async (fastify, options) => {
         };
     }
     /**
-     * The postMessage contract a silent (`prompt=none`) `{routePrefix}/callback` answers
-     * with (AK-14, gap 2) — read by `./client/silentAuth.ts`'s hidden-iframe listener.
-     * Never rendered by a top-level navigation: only ever loaded inside the hidden iframe
-     * `attemptSilentResume()` creates, so this is safe to keep unauthenticated/undecorated
-     * HTML — generalized from media-planner's `routes/auth.ts`'s `sendSilentResult`.
+     * 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.
      */
-    function sendSilentResult(reply, status, detail) {
-        const message = {
-            source: SILENT_AUTH_MESSAGE_SOURCE,
-            status,
-            detail: detail ?? null,
-        };
+    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(`<!doctype html><html><body><script>` +
-            `if (window.parent && window.parent !== window) {` +
-            `window.parent.postMessage(${JSON.stringify(message)}, ${JSON.stringify(silentAuthTargetOrigin)});` +
-            `}` +
-            `</script></body></html>`);
+            .send(page.html);
     }
     const authorizationCache = new Map();
     const EXPIRY_SKEW_MS = 5_000;
     /**
      * Returns a live IdP access token for this session — the one already on the row if
-     * it's not near expiry, otherwise a freshly refreshed one (persisted back via
-     * store.updateIdpSession before returning, since flytedesk-id rotates the refresh
-     * token on every use — see ./oidc-client.ts's refreshIdpTokens doc comment). Shared
-     * by authorizeIdpSession (below, and therefore by both loadAuthedUser and POST
-     * {routePrefix}/refresh) and the GET {routePrefix}/apps route, so the refresh
-     * behaviour — and its failure classification — can't drift between call sites.
-     * Throws IdpAccessRevokedError (nothing left to refresh with, or flytedesk-id
-     * rejected the refresh token) or IdpUnavailableError (an outage) — never swallows;
-     * every caller is expected to log what it decides to do with the failure (fail
-     * loudly, AK-16).
+     * it's not near expiry, otherwise a freshly refreshed one (persisted back before
+     * returning, since flytedesk-id rotates the refresh token on every use — see
+     * ./oidc-client.ts's refreshIdpTokens doc comment). Shared by authorizeIdpSession
+     * (below, and therefore by both loadAuthedUser and POST {routePrefix}/refresh) and the
+     * GET {routePrefix}/apps route, so the refresh behaviour — and its failure
+     * classification — can't drift between call sites.
      *
-     * AK-20, gap 2326: the actual refresh happens under `store.withIdpSessionLock`, and
-     * RE-READS the session once the lock is held — flytedesk-id rotates its own refresh
-     * token on every use, so two concurrent requests on the same near-expiry session
-     * would otherwise both read "stale" before either write landed, both present the
-     * SAME (about-to-be-consumed) refresh token to flytedesk-id, and the loser would get
-     * an otherwise perfectly good session signed out. The re-read lets a lock loser
-     * notice a sibling already refreshed while it waited and reuse that result instead of
-     * refreshing again.
+     * AK-20, gap 2326: the refresh happens under `store.withIdpSessionLock`, and RE-READS
+     * the session once the lock is held, so a lock loser notices a sibling already
+     * refreshed while it waited and reuses that result instead of refreshing (and
+     * rotating flytedesk-id's refresh token) again.
+     *
+     * AK-23: every read and write inside the lock goes through `locked`, the store
+     * `withIdpSessionLock` binds to the lock's own transaction — never through `store`
+     * itself, which would need a second pooled connection per lock holder and starve the
+     * pool under load (see `AuthStore.withIdpSessionLock`'s doc comment).
+     *
+     * AK-23 (N1): `fn` never throws on purpose — it RETURNS its outcome
+     * (`LockedRefreshOutcome`), and a failure is thrown here, only after
+     * `withIdpSessionLock` has resolved, i.e. after the store committed the lock's
+     * transaction. A store rolls that transaction back when `fn` throws (node-postgres
+     * `BEGIN`/`ROLLBACK` and Prisma's `$transaction` both do), so throwing from inside `fn`
+     * after `locked.updateIdpSession` persisted flytedesk-id's rotated refresh token would
+     * roll the only copy of it back. The one thing left that can reject
+     * `withIdpSessionLock` is the lock or the store itself.
+     *
+     * Throws exactly one of three types, never anything else:
+     *  - IdpAccessRevokedError: nothing left to refresh with, or flytedesk-id rejected the
+     *    refresh token — a verdict, the session is over.
+     *  - IdpUnavailableError: flytedesk-id is down, timed out, or answered unusably — not
+     *    a verdict.
+     *  - AuthStoreError: the lock or a store call failed (including a lock timeout) — not
+     *    a verdict.
      */
     async function getLiveIdpAccessToken(session) {
         if (session.idpAccessTokenExpiresAt.getTime() - EXPIRY_SKEW_MS >= Date.now()) {
             return session.idpAccessToken;
         }
+        let outcome;
         try {
-            return await store.withIdpSessionLock(session.id, async () => {
-                const fresh = await store.findIdpSession(session.id);
-                if (!fresh) {
-                    throw new IdpAccessRevokedError("IdP session no longer exists — re-login required");
-                }
-                if (fresh.idpAccessTokenExpiresAt.getTime() - EXPIRY_SKEW_MS >= Date.now()) {
-                    // A sibling request already refreshed this session while this one waited for
-                    // the lock — reuse its result rather than refreshing (and rotating) again.
-                    return fresh.idpAccessToken;
-                }
-                if (!fresh.idpRefreshToken) {
-                    throw new IdpAccessRevokedError("No IdP refresh token on this session — re-login required");
-                }
-                const refreshed = await oidc.refreshIdpTokens(fresh.idpRefreshToken);
-                await store.updateIdpSession(fresh.id, {
-                    idpAccessToken: refreshed.access_token,
-                    idpAccessTokenExpiresAt: new Date(Date.now() + refreshed.expires_in * 1000),
-                    idpRefreshToken: refreshed.refresh_token ?? fresh.idpRefreshToken,
-                });
-                return refreshed.access_token;
-            });
+            outcome = await store.withIdpSessionLock(session.id, (locked) => refreshUnderLock(locked, session.id));
         }
         catch (err) {
-            throw classifyIdpError(err);
+            // `refreshUnderLock` returns every IdP outcome instead of throwing it, so anything
+            // thrown here came from the lock or the locked store — including a lock timeout.
+            throw new AuthStoreError("AuthStore.withIdpSessionLock failed", err);
         }
+        if (!outcome.ok)
+            throw outcome.error;
+        return outcome.accessToken;
+    }
+    /**
+     * The body of `getLiveIdpAccessToken`'s lock: re-reads the session once the lock is
+     * held, refreshes the IdP tokens unless a sibling already did, and persists the result
+     * through `locked`. RETURNS every IdP outcome — never throws one (see
+     * `getLiveIdpAccessToken`'s N1 note); only a `locked` store call can throw.
+     */
+    async function refreshUnderLock(locked, sessionId) {
+        const fresh = await locked.findIdpSession(sessionId);
+        if (!fresh) {
+            return { ok: false, error: new IdpAccessRevokedError("IdP session no longer exists — re-login required") };
+        }
+        if (fresh.idpAccessTokenExpiresAt.getTime() - EXPIRY_SKEW_MS >= Date.now()) {
+            // A sibling request already refreshed this session while this one waited for the
+            // lock — reuse its result rather than refreshing (and rotating) again.
+            return { ok: true, accessToken: fresh.idpAccessToken };
+        }
+        if (!fresh.idpRefreshToken) {
+            return { ok: false, error: new IdpAccessRevokedError("No IdP refresh token on this session — re-login required") };
+        }
+        let refreshed;
+        try {
+            refreshed = await oidc.refreshIdpTokens(fresh.idpRefreshToken);
+        }
+        catch (err) {
+            return { ok: false, error: classifyIdpError(err) };
+        }
+        // AK-23 (residual risk — see AuthStore.withIdpSessionLock's doc comment): from here
+        // on, flytedesk-id has ALREADY rotated its refresh token, and the only copy of the
+        // new one is in `refreshed`. Persisting it is therefore the FIRST thing that can
+        // fail, and the patch is built with no step that can throw — an unusable
+        // `expires_in` becomes "already stale" (the next request refreshes again, with the
+        // token persisted here) instead of an Invalid Date the store would reject.
+        const accessTokenValid = typeof refreshed.access_token === "string" && refreshed.access_token.length > 0;
+        await locked.updateIdpSession(fresh.id, {
+            idpRefreshToken: refreshed.refresh_token ?? fresh.idpRefreshToken,
+            ...(accessTokenValid
+                ? { idpAccessToken: refreshed.access_token, idpAccessTokenExpiresAt: idpAccessTokenExpiresAt(refreshed) }
+                : {}),
+        });
+        if (!accessTokenValid) {
+            // The rotated refresh token is persisted above — and committed, because this is
+            // returned, not thrown. Only this answer is unusable.
+            return { ok: false, error: new IdpUnavailableError("flytedesk-id refresh response carried no access_token") };
+        }
+        return { ok: true, accessToken: refreshed.access_token };
     }
     /**
      * The authorization pipeline shared by loadAuthedUser (below, run on every
@@ -177,16 +262,16 @@ const flytedeskAuthPlugin = async (fastify, options) => {
      * {routePrefix}/refresh (AK-20, gap 2) — refreshes the IdP token pair if it's near
      * expiry, then calls flytedesk-id's authorization endpoint fresh (see
      * FlytedeskAuthOptions.authorizationCacheTtlMs for the one opt-in exception), builds
-     * the AuthedUser, then runs the onAuthorizeUser hook if configured. Extracted into one
-     * function specifically so `/refresh` can never drift from what an ordinary
-     * authenticated request would decide: a refresh must not mint a fresh access token for
-     * a user this SAME pipeline would reject (e.g. a suspended user) — otherwise that user
-     * could keep refreshing (rotating their family, extending its lifetime) indefinitely
-     * even though every resource request the minted token is then used for still 401s.
-     * Never throws: any failure just means no AuthedUser — the caller decides what that
-     * means for its own route. Every failure that is NOT a routine "nothing to refresh
-     * with" outcome is still logged with context (fail loudly, AK-16), distinguishing a
-     * flytedesk-id outage from a genuinely revoked session.
+     * the AuthedUser, then runs the onAuthorizeUser hook if configured. One function so
+     * `/refresh` can never drift from what an ordinary authenticated request would decide:
+     * a refresh must not mint a fresh access token for a user this SAME pipeline would
+     * reject (e.g. a suspended user).
+     *
+     * Never throws. AK-23: it answers one of three outcomes (see `AuthorizationOutcome`),
+     * and only `rejected` is a verdict — 3.x collapsed an outage, a lock timeout and a
+     * throwing hook into the same "no user" answer as a real rejection, so an IdP outage
+     * during `/refresh` revoked every refreshing session. Every failure is logged here
+     * with context (fail loudly, AK-16), distinguishing an outage from a revocation.
      */
     async function authorizeIdpSession(request, session) {
         let idpAccessToken;
@@ -194,11 +279,15 @@ const flytedeskAuthPlugin = async (fastify, options) => {
             idpAccessToken = await getLiveIdpAccessToken(session);
         }
         catch (err) {
-            const classified = classifyIdpError(err);
-            request.log.error({ err: classified, sid: session.id }, classified instanceof IdpAccessRevokedError
-                ? "@flytedesk/app-kit/auth: flytedesk-id refresh token revoked or expired — forcing re-login"
-                : "@flytedesk/app-kit/auth: flytedesk-id token refresh failed — possible IdP outage");
-            return undefined;
+            const failure = err;
+            if (failure instanceof IdpAccessRevokedError) {
+                request.log.error({ err: failure, sid: session.id }, "@flytedesk/app-kit/auth: flytedesk-id refresh token revoked or expired — forcing re-login");
+                return { kind: "rejected" };
+            }
+            request.log.error({ err: failure, sid: session.id }, failure instanceof AuthStoreError
+                ? "@flytedesk/app-kit/auth: AuthStore failed while refreshing the IdP token — not a rejection"
+                : "@flytedesk/app-kit/auth: flytedesk-id token refresh failed — possible IdP outage, not a rejection");
+            return { kind: "unavailable", code: unavailableCodeFor(failure) };
         }
         let authorization;
         if (options.authorizationCacheTtlMs) {
@@ -212,10 +301,12 @@ const flytedeskAuthPlugin = async (fastify, options) => {
             }
             catch (err) {
                 const classified = classifyIdpError(err);
-                request.log.error({ err: classified, sid: session.id }, classified instanceof IdpAccessRevokedError
-                    ? "@flytedesk/app-kit/auth: flytedesk-id revoked this session's authorization"
-                    : "@flytedesk/app-kit/auth: flytedesk-id authorization lookup failed — possible IdP outage");
-                return undefined;
+                if (classified instanceof IdpAccessRevokedError) {
+                    request.log.error({ err: classified, sid: session.id }, "@flytedesk/app-kit/auth: flytedesk-id revoked this session's authorization");
+                    return { kind: "rejected" };
+                }
+                request.log.error({ err: classified, sid: session.id }, "@flytedesk/app-kit/auth: flytedesk-id authorization lookup failed — possible IdP outage, not a rejection");
+                return { kind: "unavailable", code: "idp_unavailable" };
             }
             if (options.authorizationCacheTtlMs) {
                 authorizationCache.set(session.id, {
@@ -237,80 +328,89 @@ const flytedeskAuthPlugin = async (fastify, options) => {
             permissions: authorization.permissions.map((p) => (p.startsWith(prefix) ? p.slice(prefix.length) : p)),
         };
         // AK-14, gap 4: the one extension point a consumer has to reject or enrich an
-        // otherwise-valid, still-IdP-authorized session on every request (e.g. media-planner's
-        // own local suspension flag) — see FlytedeskAuthOptions.onAuthorizeUser's doc comment.
-        // A throwing/rejecting hook is treated exactly like a `null` return: fail loudly
-        // (logged with context, AK-16) but never a 500 — a hook error must never be
-        // indistinguishable from "authenticated".
+        // otherwise-valid, still-IdP-authorized session on every request — see
+        // FlytedeskAuthOptions.onAuthorizeUser's doc comment. `null` is a verdict; a throw is
+        // not (AK-23): the hook could not decide, so the request is unauthenticated but
+        // nothing is revoked.
         if (options.onAuthorizeUser) {
             let authorized;
             try {
                 authorized = await options.onAuthorizeUser(user, request);
             }
             catch (err) {
-                request.log.error({ err, sid: session.id }, "@flytedesk/app-kit/auth: onAuthorizeUser threw — treating the session as rejected");
-                return undefined;
+                request.log.error({ err, sid: session.id }, "@flytedesk/app-kit/auth: onAuthorizeUser threw — request not authenticated, session not revoked");
+                return { kind: "unavailable", code: "authorization_hook_failed" };
             }
-            if (!authorized)
-                return undefined;
-            return authorized;
+            return authorized ? { kind: "authorized", user: authorized } : { kind: "rejected" };
         }
-        return user;
+        return { kind: "authorized", user };
     }
     /**
-     * Live per-request by default: resolves `request.authUser` from the access token's
-     * `sid` by looking up the IdpSession, then running it through authorizeIdpSession
-     * above. Never throws: any failure just means no AuthedUser gets attached —
-     * requireAuth 401s from there.
+     * Live per-request by default: looks up the IdpSession behind the access token's
+     * `sid`, then runs it through authorizeIdpSession above. Never throws. A missing
+     * session (or one for another subject) is `rejected`; a store failure looking it up
+     * is `unavailable` (AK-23) — the store being down says nothing about the session.
      */
-    async function loadAuthedUser(request, claims) {
+    async function loadAuthorization(request, claims) {
         let session;
         try {
-            session = await store.findIdpSession(claims.sid);
+            session = await storeCall("findIdpSession", () => store.findIdpSession(claims.sid));
         }
         catch (err) {
-            request.log.error({ err: new AuthStoreError("AuthStore.findIdpSession failed", err), sid: claims.sid }, "@flytedesk/app-kit/auth: AuthStore error looking up IdP session");
-            return undefined;
+            request.log.error({ err, sid: claims.sid }, "@flytedesk/app-kit/auth: AuthStore error looking up IdP session — not a rejection");
+            return { kind: "unavailable", code: "auth_store_unavailable" };
         }
         if (!session || session.subject !== claims.sub)
-            return undefined; // no session for this claim — expected, not an error
+            return { kind: "rejected" }; // expected, not an error
         return authorizeIdpSession(request, session);
     }
     // onRequest, not preHandler: this needs to run before any route-level preHandler
-    // (requireAuth/requirePermission included) so request.authUser is already resolved
-    // by the time those run.
+    // (requireAuth/requirePermission included) so request.authUser — or, when the plugin
+    // could not decide, request.authUnavailable (AK-23: requireAuth then answers 503, not
+    // 401) — is already resolved by the time those run.
     fastify.addHook("onRequest", async (request) => {
         const header = request.headers.authorization;
         if (!header?.startsWith("Bearer "))
             return;
+        let claims;
         try {
-            const claims = await verifyAccessToken(options.accessTokenSecret, header.slice(7));
-            const user = await loadAuthedUser(request, claims);
-            if (user)
-                request.authUser = user;
+            claims = await verifyAccessToken(options.accessTokenSecret, header.slice(7));
         }
         catch {
             // Invalid/expired access token: leave request.authUser unset; requireAuth 401s.
+            return;
         }
+        const outcome = await loadAuthorization(request, claims);
+        if (outcome.kind === "authorized")
+            request.authUser = outcome.user;
+        else if (outcome.kind === "unavailable")
+            request.authUnavailable = outcome.code;
     });
-    async function issueSession(request, reply, userId, idpSessionId, familyId) {
-        const { token: refreshToken, hash } = generateRefreshToken();
-        const expiresAt = new Date(Date.now() + refreshTokenTtlSeconds * 1000);
-        await store.createRefreshToken({
-            id: randomUUID(),
-            familyId,
-            userId,
-            tokenHash: hash,
-            expiresAt,
-            idpSessionId,
-            userAgent: request.headers["user-agent"] ?? null,
-            ip: request.ip,
-            // The first token of a fresh login — nothing precedes it in the family.
-            replacesId: null,
-        });
-        const { token: accessToken, expiresAt: accessExpiresAt } = await signAccessToken(options.accessTokenSecret, accessTokenTtlSeconds, userId, idpSessionId);
+    /** An opaque refresh token for one family: the raw token for the cookie, and the row
+     *  (its hash, never the token) to persist. `issued` is the token itself — random for a
+     *  login's first token (`generateRefreshToken`), derived from the presented row and token for
+     *  a rotation (`successorRefreshToken`, see `resumeSuccessor`). */
+    function newRefreshToken(request, family, { token, hash }) {
+        return {
+            token,
+            row: {
+                id: randomUUID(),
+                familyId: family.familyId,
+                userId: family.userId,
+                tokenHash: hash,
+                expiresAt: new Date(Date.now() + refreshTokenTtlSeconds * 1000),
+                idpSessionId: family.idpSessionId,
+                userAgent: request.headers["user-agent"] ?? null,
+                ip: request.ip,
+            },
+        };
+    }
+    /** The success tail shared by login and `/refresh`: hands the browser its (new) refresh
+     *  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));
-        return { accessToken, accessTokenExpiresAt: accessExpiresAt.toISOString() };
+        return { accessToken, accessTokenExpiresAt: expiresAt.toISOString() };
     }
     /**
      * GET {routePrefix}/login — starts the flytedesk-id sign-in. A plain redirect meant
@@ -422,19 +522,25 @@ const flytedeskAuthPlugin = async (fastify, options) => {
         }
         const silent = stash?.silent === true;
         /**
-         * Answers ONE callback failure. Silent (AK-14): unchanged — the postMessage page,
-         * carrying the raw internal `code`, consumed only inside the hidden iframe
-         * (`sendSilentResult` above); never a top-level navigation, so it was never the
-         * raw-JSON dead end this card fixes. 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 — so no call site has to remember to log it itself.
+         * 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 (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
@@ -477,7 +583,7 @@ 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);
+                await options.onSignIn(profile, request, { mode: silent ? "silent" : "interactive" });
             }
             const name = profile.name ?? profile.email.split("@")[0];
             const idpSession = await store.createIdpSession({
@@ -485,15 +591,16 @@ const flytedeskAuthPlugin = async (fastify, options) => {
                 name,
                 email: profile.email,
                 idpAccessToken: tokens.access_token,
-                idpAccessTokenExpiresAt: new Date(Date.now() + tokens.expires_in * 1000),
+                idpAccessTokenExpiresAt: idpAccessTokenExpiresAt(tokens),
                 idpRefreshToken: tokens.refresh_token ?? null,
             });
             // A fresh family for every login — reuse detection (see POST /refresh below)
             // only ever revokes the chain descended from one login, never sibling sessions.
-            const familyId = randomUUID();
-            await issueSession(request, reply, profile.sub, idpSession.id, familyId);
+            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 — issueSession() above already set the real
+                // 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
@@ -509,143 +616,244 @@ const flytedeskAuthPlugin = async (fastify, options) => {
     });
     /** The one answer POST {routePrefix}/refresh gives a refresh token it will not
      *  rotate. `clearCookie` only for a token that is genuinely dead (unrecognized,
-     *  expired, or reused — its whole family just ended); NOT for one that merely lost a
-     *  concurrent-tab race (AK-14, gap 3; MP-127): the winner is setting the browser's
-     *  fresh cookie at the same moment, and a clearing Set-Cookie on the loser's response
-     *  can land after it and delete the fresh token. */
+     *  expired, revoked, or reused — its whole family just ended); NOT for one that merely
+     *  lost a concurrent-tab race (AK-14, gap 3; MP-127): the winner is setting the
+     *  browser's fresh cookie at the same moment, and a clearing Set-Cookie on the loser's
+     *  response can land after it and delete the fresh token. */
     function rejectRefresh(reply, { clearCookie }) {
         if (clearCookie)
             reply.clearCookie(refreshCookieName, { path: cookiePath });
         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 });
+        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. */
+    function clientOf(request) {
+        return { ip: request.ip, userAgent: request.headers["user-agent"] ?? null };
+    }
+    /**
+     * Refresh-token reuse: revokes `replayed`'s whole family (`reuse_detected` — every token
+     * downstream of the replayed one must be assumed compromised) and answers 401
+     * `token_reuse_detected` with the cookie cleared.
+     */
+    async function reportReuse(request, reply, replayed, sinceRotatedMs, why) {
+        const client = clientOf(request);
+        const context = { familyId: replayed.familyId, userId: replayed.userId, sinceRotatedMs, why, ...client };
+        request.log.warn(context, "@flytedesk/app-kit/auth: refresh token reuse detected — revoking token family");
+        try {
+            await storeCall("revokeFamily", () => store.revokeFamily(replayed.familyId, { type: "reuse_detected", replayedToken: replayed, sinceRotatedMs, ...client }, new Date()));
+        }
+        catch (err) {
+            // Reuse was DETECTED but not recorded: the family (and whichever live successor
+            // the thief or the victim holds) is still live. The answer stays 503 with the
+            // cookie kept, not 401: a 401 would end this client's retries, and each retry is
+            // what re-presents this replayed token and re-attempts the revocation — it is the
+            // only thing that ever will. The replayed token itself is already rotated, and it
+            // is never resumed outside the grace window.
+            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 });
+        reply.code(401).send({ error: "Refresh token reuse detected", code: "token_reuse_detected" });
+    }
     /**
      * POST {routePrefix}/refresh — no body, reads the refresh cookie. Rotates it on every
      * successful call.
      *
-     * A presented token can be rejected two different ways (AK-14, gap 3; MP-127; RFC
-     * 9700 §4.14.2), and telling them apart is the whole point of this route:
+     * ONE clock (AK-23): every time this route compares or records is the app's clock,
+     * never the database's `now()`. Comparisons read the clock once, at the start of the
+     * request (`now`); every revocation time is read from it again AT the store write
+     * (`new Date()` passed to `rotateRefreshToken`/`revokeFamily`), because the
+     * authorization step before a rotation can legitimately take seconds (a session-lock
+     * wait, a flytedesk-id `/token` call, the authorization hook) — a time stamped at the
+     * request's start would land early and shrink the grace window for the very retry it
+     * exists for.
+     *
+     * A presented token that is already revoked (`stored.revocation`, from
+     * `findRefreshTokenByHash`) is answered by WHY it was revoked (AK-23):
+     *
+     *  - `"rotated"`, less than `refreshReuseGraceMs` ago: the same browser presenting it
+     *    again — a concurrent tab whose request was in flight when it was rotated, or a
+     *    browser whose refresh response never arrived (it timed out, the network dropped
+     *    it) and so still holds this cookie. Tabs share one cookie jar, so only the
+     *    IMMEDIATELY previous token can legitimately come back (the policy Auth0's reuse
+     *    interval follows): `resumeSuccessor` re-derives its direct successor
+     *    (`successorRefreshToken`) and, when that is the family's live token, answers with
+     *    it — authorized through the same pipeline, rotated no further. A token two or
+     *    more rotations back is reuse.
+     *  - `"rotated"`, outside that window: reuse (`reportReuse`).
+     *  - anything else (`signed_out`, `authorization_rejected`, `reuse_detected`): the
+     *    family was already ended on purpose. 401, cookie cleared, nothing revoked or
+     *    reported again — 3.x reported these as reuse, so a tab that fired one last refresh
+     *    after sign-out raised a false security alarm.
+     *
+     * A token that looked live is authorized through the SAME pipeline `loadAuthedUser`
+     * runs on every request (AK-20, gap 2) before it is rotated. Only a definitive
+     * rejection revokes the family (`authorization_rejected`); an outage, a lock timeout,
+     * a store error or a throwing `onAuthorizeUser` answers 503 and revokes nothing
+     * (AK-23) — an IdP outage used to sign out every user who refreshed during it. The
+     * pipeline runs BEFORE the rotation, not between a claim and a mint: it can be slow
+     * (a real round trip to flytedesk-id), and the rotation must stay one short atomic
+     * step.
      *
-     *  - It was ALREADY revoked before this request even started
-     *    (`stored.revokedAt`, from `findRefreshTokenByHash`'s own read, is non-null) — a
-     *    LATE event, from this request's point of view. If it was rotated
-     *    (`stored.rotated`) and that rotation happened less than `refreshReuseGraceMs`
-     *    ago, it's still plausibly a concurrent-tab race whose loser's request simply
-     *    took a while to arrive: 401, nothing revoked. Otherwise (never rotated at all, or
-     *    outside the window) it's reuse: the whole family is revoked, since every token
-     *    downstream of the replayed one must be assumed compromised too.
-     *  - It looked live at that same read (`revokedAt: null`), but a SIBLING request
-     *    claims it first (`store.claimRefreshTokenForRotation` returns `false`) — a
-     *    genuine, same-instant concurrent-tab race, decided purely by that method's
-     *    atomicity. Treated as a race unconditionally: no rotated/timing check needed
-     *    (there's nothing to check yet — the winner's rotation is still in flight), 401,
-     *    nothing revoked. This mirrors media-planner's own shape exactly
-     *    (`updateMany({revokedAt: null}); if (count !== 1) return false`).
+     * Rotation is `store.rotateRefreshToken` — the revoke of the presented token and the
+     * insert of its successor are one transaction (AK-23), so a failure can never leave a
+     * revoked token without a successor. `false` means a sibling request rotated it first
+     * in the moment since the read above: this request is then exactly the in-grace second
+     * presentation above, and is answered as one.
      *
-     * The claim happens BEFORE the expiry check and is what actually detects that second
-     * kind of loss — not a re-read of `revokedAt`, which would leave the exact window this
-     * method exists to close: two concurrent requests both observing "not yet revoked"
-     * before either write lands. See `AuthStore.claimRefreshTokenForRotation`'s doc
-     * comment in ./types.ts.
+     * Any store failure anywhere in this route answers 503 `auth_store_unavailable`
+     * without touching the cookie.
+     *
+     * Every helper below ANSWERS the request and resolves `void` (or a boolean saying
+     * whether it answered): a `FastifyReply` is a thenable, so an async function that
+     * returned one would resolve to `undefined` once it was sent, never to the reply.
      */
     fastify.post(authRoutePath(routePrefix, "refresh"), async (request, reply) => {
         const token = request.cookies[refreshCookieName];
         if (!token) {
             return reply.code(401).send({ error: "No refresh token", code: "unauthenticated" });
         }
-        const hash = hashRefreshToken(token);
-        const stored = await store.findRefreshTokenByHash(hash);
+        try {
+            await refreshSession(request, reply, token, new Date());
+        }
+        catch (err) {
+            if (!(err instanceof AuthStoreError))
+                throw err;
+            request.log.error({ err }, "@flytedesk/app-kit/auth: /refresh AuthStore failure — answering 503, nothing revoked");
+            sendAuthUnavailable(reply, "auth_store_unavailable");
+        }
+        return reply;
+    });
+    /** POST {routePrefix}/refresh's body — see that route's doc comment. Store calls go
+     *  through `storeCall`, so every storage failure surfaces as `AuthStoreError`. */
+    async function refreshSession(request, reply, token, now) {
+        const stored = await storeCall("findRefreshTokenByHash", () => store.findRefreshTokenByHash(hashRefreshToken(token)));
         if (!stored) {
             reply.clearCookie(refreshCookieName, { path: cookiePath });
-            return reply.code(401).send({ error: "Refresh token not recognized", code: "unauthenticated" });
+            reply.code(401).send({ error: "Refresh token not recognized", code: "unauthenticated" });
+            return;
+        }
+        if (stored.revocation) {
+            await answerRevokedPresentation(request, reply, stored, stored.revocation, token, now);
+            return;
+        }
+        if (stored.expiresAt < now) {
+            reply.clearCookie(refreshCookieName, { path: cookiePath });
+            reply.code(401).send({ error: "Refresh token expired", code: "unauthenticated" });
+            return;
         }
-        if (stored.revokedAt) {
-            const sinceRevokedMs = Date.now() - stored.revokedAt.getTime();
-            if (stored.rotated && sinceRevokedMs < refreshReuseGraceMs) {
-                return rejectRefresh(reply, { clearCookie: false });
+        if (await authorizeRefresh(request, reply, stored))
+            return;
+        const next = newRefreshToken(request, stored, successorRefreshToken(successorKey, stored.id, token));
+        const rotated = await storeCall("rotateRefreshToken", () => store.rotateRefreshToken(stored.id, next.row, new Date()));
+        if (!rotated) {
+            // A sibling request rotated (or revoked) it in the moment since the read above:
+            // answer this request as the second presentation it has become.
+            const reread = await storeCall("findRefreshTokenByHash", () => store.findRefreshTokenByHash(hashRefreshToken(token)));
+            if (reread?.revocation) {
+                await answerRevokedPresentation(request, reply, reread, reread.revocation, token, now);
             }
-            request.log.warn({
-                familyId: stored.familyId,
-                userId: stored.userId,
-                rotated: stored.rotated,
-                sinceRevokedMs,
-            }, "@flytedesk/app-kit/auth: refresh token reuse detected — revoking token family");
-            await store.revokeFamily(stored.familyId, {
-                type: "reuse_detected",
-                replayedToken: stored,
-                sinceRotatedMs: sinceRevokedMs,
-                ip: request.ip,
-                userAgent: request.headers["user-agent"] ?? null,
-            });
-            reply.clearCookie(refreshCookieName, { path: cookiePath });
-            return reply.code(401).send({ error: "Refresh token reuse detected", code: "token_reuse_detected" });
+            else {
+                rejectRefresh(reply, { clearCookie: false });
+            }
+            return;
         }
-        if (stored.expiresAt < new Date()) {
-            reply.clearCookie(refreshCookieName, { path: cookiePath });
-            return reply.code(401).send({ error: "Refresh token expired", code: "unauthenticated" });
-        }
-        // AK-20, gap 2: run the SAME authorization pipeline loadAuthedUser runs on every
-        // other authenticated request — including onAuthorizeUser — before minting a fresh
-        // access token. Without this, a user the app suspended (via onAuthorizeUser) could
-        // keep refreshing forever: their resource requests with the minted token would
-        // still 401, but nothing ever ended the session, so their family kept rotating and
-        // its lifetime kept extending indefinitely. A rejection here revokes the whole
-        // family, exactly like a detected reuse — the point of rotating at all is defeated
-        // if a rejected user's family just keeps living. Deliberately BEFORE the atomic
-        // claim below (not after): this call can be slow (a real network round trip to
-        // flytedesk-id), and running it between the claim and the mint would widen the
-        // window in which a genuinely concurrent sibling request's read of this same row
-        // could land — the atomic claim and the mint that follows it must stay adjacent,
-        // exactly as they were before this card, or the plugin's own concurrent-tab-race
-        // handling (gap 3) becomes measurably flakier under load, not just under test.
-        let idpSession;
-        try {
-            idpSession = await store.findIdpSession(stored.idpSessionId);
+        reply.send(await completeSession(reply, next.token, stored.userId, stored.idpSessionId));
+    }
+    /** A presented token that is already revoked — see POST {routePrefix}/refresh's doc
+     *  comment for the three answers. */
+    async function answerRevokedPresentation(request, reply, presented, revocation, token, now) {
+        const sinceRotatedMs = now.getTime() - revocation.at.getTime();
+        if (revocation.reason !== "rotated") {
+            request.log.info({ familyId: presented.familyId, userId: presented.userId, revokedReason: revocation.reason, sinceRotatedMs }, "@flytedesk/app-kit/auth: refresh token from an already-ended family presented — not reuse, nothing revoked");
+            rejectRefresh(reply, { clearCookie: true });
+            return;
         }
-        catch (err) {
-            request.log.error({ err: new AuthStoreError("AuthStore.findIdpSession failed", err), idpSessionId: stored.idpSessionId }, "@flytedesk/app-kit/auth: /refresh AuthStore error looking up IdP session");
-            return reply.code(502).send({ error: "Could not load the signed-in session", code: "auth_store_failed" });
+        if (sinceRotatedMs >= refreshReuseGraceMs) {
+            await reportReuse(request, reply, presented, sinceRotatedMs, "presented outside the grace window");
+            return;
         }
+        await resumeSuccessor(request, reply, presented, token, sinceRotatedMs, now);
+    }
+    /**
+     * Runs the authorization pipeline for the session behind `row` before `/refresh`
+     * issues anything for it. When the answer is not "authorized" it answers the request
+     * itself (a rejection revokes the family; an outage is a 503) and returns `true`;
+     * otherwise `false`.
+     */
+    async function authorizeRefresh(request, reply, row) {
+        const idpSession = await storeCall("findIdpSession", () => store.findIdpSession(row.idpSessionId));
         if (!idpSession) {
-            request.log.warn({ familyId: stored.familyId, idpSessionId: stored.idpSessionId }, "@flytedesk/app-kit/auth: /refresh — no IdP session left for this refresh token — revoking family");
-            await store.revokeFamily(stored.familyId, { type: "authorization_rejected" });
-            reply.clearCookie(refreshCookieName, { path: cookiePath });
-            return reply.code(401).send({ error: "Session not found", code: "unauthenticated" });
+            request.log.warn({ familyId: row.familyId, idpSessionId: row.idpSessionId }, "@flytedesk/app-kit/auth: /refresh — no IdP session left for this refresh token — revoking family");
+            await rejectFamily(reply, row);
+            return true;
+        }
+        const outcome = await authorizeIdpSession(request, idpSession);
+        if (outcome.kind === "unavailable") {
+            // authorizeIdpSession already logged the cause.
+            sendAuthUnavailable(reply, outcome.code);
+            return true;
+        }
+        if (outcome.kind === "rejected") {
+            request.log.warn({ familyId: row.familyId, userId: row.userId }, "@flytedesk/app-kit/auth: /refresh rejected by the authorization check — revoking token family");
+            await rejectFamily(reply, row);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Answers an in-grace second presentation of the rotated token `presented` (see POST
+     * {routePrefix}/refresh's doc comment) with its DIRECT successor — re-derived with
+     * `successorRefreshToken` from the presented row's server-side id and the token — when
+     * that successor is the family's live token: authorized, then issued again with a fresh
+     * access token, rotating nothing. Exactly one hop:
+     *
+     *  - the successor was itself rotated since (the token is two or more rotations back),
+     *    or it belongs to another family: reuse.
+     *  - the successor's family was ended on purpose: 401, cookie cleared.
+     *  - the successor expired: 401, cookie cleared.
+     *  - no successor row at all — the rotation was derived under a different
+     *    `accessTokenSecret` (a rolling secret change: see the README) or predates this
+     *    derivation: 401, cookie kept, nothing revoked.
+     */
+    async function resumeSuccessor(request, reply, presented, token, sinceRotatedMs, now) {
+        const successor = successorRefreshToken(successorKey, presented.id, token);
+        const head = await storeCall("findRefreshTokenByHash", () => store.findRefreshTokenByHash(successor.hash));
+        if (!head) {
+            rejectRefresh(reply, { clearCookie: false });
+            return;
+        }
+        if (head.familyId !== presented.familyId) {
+            await reportReuse(request, reply, presented, sinceRotatedMs, "its derived successor belongs to another family");
+            return;
+        }
+        if (head.revocation?.reason === "rotated") {
+            await reportReuse(request, reply, presented, sinceRotatedMs, "presented two or more rotations back");
+            return;
         }
-        const authorized = await authorizeIdpSession(request, idpSession);
-        if (!authorized) {
-            request.log.warn({ familyId: stored.familyId, userId: stored.userId }, "@flytedesk/app-kit/auth: /refresh rejected by the authorization check — revoking token family");
-            await store.revokeFamily(stored.familyId, { type: "authorization_rejected" });
+        if (head.revocation || head.expiresAt < now) {
             reply.clearCookie(refreshCookieName, { path: cookiePath });
-            return reply.code(401).send({ error: "Authorization rejected", code: "unauthenticated" });
-        }
-        const claimed = await store.claimRefreshTokenForRotation(stored.id);
-        if (!claimed) {
-            // A sibling request claimed it first, in the tiny window since the read above —
-            // a same-instant concurrent-tab race, not reuse (see the route's doc comment).
-            return rejectRefresh(reply, { clearCookie: false });
-        }
-        // Rotate: the claim above already revoked the used token; issue a fresh one in the
-        // same family — limits replay if a cookie leaks, and idpSessionId carries forward
-        // unchanged so this session's link to its flytedesk-id token pair survives the
-        // rotation. `replacesId` records the rotation so a later reuse-vs-race decision on
-        // THIS token (`stored.id`) can find it.
-        const next = generateRefreshToken();
-        const expiresAt = new Date(Date.now() + refreshTokenTtlSeconds * 1000);
-        await store.createRefreshToken({
-            id: randomUUID(),
-            familyId: stored.familyId,
-            userId: stored.userId,
-            tokenHash: next.hash,
-            expiresAt,
-            idpSessionId: stored.idpSessionId,
-            userAgent: request.headers["user-agent"] ?? null,
-            ip: request.ip,
-            replacesId: stored.id,
-        });
-        const { token: accessToken, expiresAt: accessExpiresAt } = await signAccessToken(options.accessTokenSecret, accessTokenTtlSeconds, stored.userId, stored.idpSessionId);
-        reply.setCookie(refreshCookieName, next.token, refreshCookieOptions(refreshTokenTtlSeconds));
-        return reply.send({ accessToken, accessTokenExpiresAt: accessExpiresAt.toISOString() });
-    });
+            reply.code(401).send({ error: "Refresh token expired or revoked", code: "unauthenticated" });
+            return;
+        }
+        if (await authorizeRefresh(request, reply, head))
+            return;
+        request.log.warn({
+            familyId: head.familyId,
+            userId: head.userId,
+            sinceRotatedMs,
+            ...clientOf(request),
+            successorIssuedToIp: head.ip,
+            successorIssuedToUserAgent: head.userAgent,
+        }, "@flytedesk/app-kit/auth: just-rotated refresh token presented again inside the grace window — answering with its successor");
+        reply.send(await completeSession(reply, successor.token, head.userId, head.idpSessionId));
+    }
     /**
      * GET {routePrefix}/apps — the "All flytedesk apps" switcher feed (flytedesk-id's
      * `GET /me/apps`, MP-213/MP-209), served by the plugin itself so every consumer gets
@@ -656,18 +864,31 @@ const flytedeskAuthPlugin = async (fastify, options) => {
      * oidc client — never exposed on request.authUser (AuthedUser deliberately carries
      * no token). Every upstream failure is mapped to a typed, logged error: never an
      * unmapped 500 carrying flytedesk-id's raw response text.
+     *
+     * AK-23 (N2): `requireAuth` has already verified the session for this very request,
+     * so nothing that fails after it says anything about the session. An outage here —
+     * flytedesk-id's `/me/apps`, its `/token`, or the AuthStore — is **502
+     * `apps_unavailable`**: the switcher feed failed, NOT one of the `AUTH_UNAVAILABLE_CODES`
+     * 503s that tell a client its session could not be verified (which would put
+     * `useAuthSession` into `"unavailable"` over a feed that is only decoration). Only
+     * flytedesk-id refusing the session's token is a 401 (`idp_access_revoked`).
      */
-    fastify.get(authRoutePath(routePrefix, "apps"), async (request, reply) => {
-        if (!request.authUser) {
-            return reply.code(401).send({ error: "Authentication required", code: "unauthenticated" });
+    fastify.get(authRoutePath(routePrefix, "apps"), { preHandler: requireAuth }, async (request, reply) => {
+        const { sessionId } = request.authUser;
+        function appsUnavailable(err, cause) {
+            request.log.error({ err, sessionId }, `@flytedesk/app-kit/auth: /apps — ${cause}; answering 502 apps_unavailable`);
+            return reply.code(502).send({ error: "The app switcher feed is unavailable right now", code: "apps_unavailable" });
+        }
+        function appsAccessRevoked(err) {
+            request.log.error({ err, sessionId }, "@flytedesk/app-kit/auth: /apps — flytedesk-id refused this session's token");
+            return reply.code(401).send({ error: "Sign-in with flytedesk-id has expired", code: "idp_access_revoked" });
         }
         let session;
         try {
-            session = await store.findIdpSession(request.authUser.sessionId);
+            session = await storeCall("findIdpSession", () => store.findIdpSession(sessionId));
         }
         catch (err) {
-            request.log.error({ err: new AuthStoreError("AuthStore.findIdpSession failed", err), sessionId: request.authUser.sessionId }, "@flytedesk/app-kit/auth: /apps AuthStore error looking up IdP session");
-            return reply.code(502).send({ error: "Could not load the signed-in session", code: "auth_store_failed" });
+            return appsUnavailable(err, "AuthStore error looking up the IdP session");
         }
         if (!session) {
             return reply.code(401).send({ error: "Session not found", code: "unauthenticated" });
@@ -677,14 +898,9 @@ const flytedeskAuthPlugin = async (fastify, options) => {
             idpAccessToken = await getLiveIdpAccessToken(session);
         }
         catch (err) {
-            const classified = classifyIdpError(err);
-            request.log.error({ err: classified, sessionId: session.id }, classified instanceof IdpAccessRevokedError
-                ? "@flytedesk/app-kit/auth: /apps — flytedesk-id refresh token revoked or expired"
-                : "@flytedesk/app-kit/auth: /apps — flytedesk-id token refresh failed, possible outage");
-            if (classified instanceof IdpAccessRevokedError) {
-                return reply.code(401).send({ error: "Sign-in with flytedesk-id has expired", code: "idp_access_revoked" });
-            }
-            return reply.code(502).send({ error: "flytedesk-id is unavailable", code: "idp_unavailable" });
+            if (err instanceof IdpAccessRevokedError)
+                return appsAccessRevoked(err);
+            return appsUnavailable(err, "refreshing the IdP access token failed");
         }
         try {
             const apps = await oidc.fetchMyApps(idpAccessToken);
@@ -692,11 +908,9 @@ const flytedeskAuthPlugin = async (fastify, options) => {
         }
         catch (err) {
             const classified = classifyIdpError(err);
-            request.log.error({ err: classified, sessionId: session.id }, "@flytedesk/app-kit/auth: /apps — flytedesk-id /me/apps lookup failed");
-            if (classified instanceof IdpAccessRevokedError) {
-                return reply.code(401).send({ error: "Sign-in with flytedesk-id has expired", code: "idp_access_revoked" });
-            }
-            return reply.code(502).send({ error: "flytedesk-id is unavailable", code: "idp_unavailable" });
+            if (classified instanceof IdpAccessRevokedError)
+                return appsAccessRevoked(classified);
+            return appsUnavailable(classified, "flytedesk-id /me/apps lookup failed");
         }
     });
     /**
@@ -709,55 +923,69 @@ const flytedeskAuthPlugin = async (fastify, options) => {
      * does, instead of every app re-declaring the same three lines and the same response
      * shape by hand.
      */
-    fastify.get(authRoutePath(routePrefix, "me"), async (request, reply) => {
-        if (!request.authUser) {
-            return reply.code(401).send({ error: "Authentication required", code: "unauthenticated" });
-        }
+    fastify.get(authRoutePath(routePrefix, "me"), { preHandler: requireAuth }, async (request, reply) => {
         return reply.send({ user: request.authUser });
     });
     /**
      * POST {routePrefix}/logout — revokes the whole refresh-token family (not just the
-     * presented cookie) and the IdpSession row, then 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 — it must never throw or block local logout either way, since
-     * the local session is what actually keeps a signed-out browser locked out.
+     * 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).
+     *
+     * 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".
      */
     fastify.post(authRoutePath(routePrefix, "logout"), async (request, reply) => {
         const token = request.cookies[refreshCookieName];
-        if (token) {
-            const hash = hashRefreshToken(token);
-            const stored = await store.findRefreshTokenByHash(hash);
-            if (stored) {
-                // Revoke the local family FIRST and unconditionally — that's what actually
-                // keeps a signed-out browser locked out, independent of anything below.
-                await store.revokeFamily(stored.familyId, { type: "signed_out" });
-                const idpSession = await store.findIdpSession(stored.idpSessionId);
-                if (idpSession?.idpRefreshToken) {
-                    // revokeIdpToken's own contract (see oidc-client.ts) is never to throw — this
-                    // is best-effort by design (flytedesk-id currently advertises no
-                    // revocation_endpoint at all), not a swallowed failure.
-                    await oidc.revokeIdpToken(idpSession.idpRefreshToken);
-                }
-                try {
-                    await store.deleteIdpSession(stored.idpSessionId);
-                }
-                catch (err) {
-                    // Fail loudly (AK-16): the family is already revoked above, so the browser is
-                    // locked out either way — but a store failure here means the IdpSession row
-                    // (and the IdP tokens it holds) leaked, which is worth surfacing rather than
-                    // reporting a silent, fully-clean "signed out".
-                    request.log.error({ err: new AuthStoreError("AuthStore.deleteIdpSession failed", err), idpSessionId: stored.idpSessionId }, "@flytedesk/app-kit/auth: logout failed to delete the IdP session — the refresh token family is revoked either way");
-                    reply.clearCookie(refreshCookieName, { path: cookiePath });
-                    return reply
-                        .code(502)
-                        .send({ error: "Sign-out did not fully complete", code: "logout_store_failed" });
-                }
-            }
+        let complete = true;
+        try {
+            if (token)
+                complete = await endSignedInSession(request, token);
+        }
+        finally {
+            reply.clearCookie(refreshCookieName, { path: cookiePath });
+        }
+        if (!complete) {
+            return reply.code(502).send({ error: "Sign-out did not fully complete", code: "logout_store_failed" });
         }
-        reply.clearCookie(refreshCookieName, { path: cookiePath });
         return reply.send({ loggedOut: true });
     });
+    /**
+     * Runs one logout store step, logging (never throwing) its failure. Returns the step's
+     * result, or `failed` so the caller can carry on with the next independent step.
+     */
+    async function logoutStep(request, method, call) {
+        try {
+            return { ok: true, value: await storeCall(method, call) };
+        }
+        catch (err) {
+            request.log.error({ err }, `@flytedesk/app-kit/auth: logout — AuthStore.${method} failed, sign-out incomplete`);
+            return { ok: false };
+        }
+    }
+    /** Ends the sign-in behind one refresh cookie; true when every step succeeded (or
+     *  there was nothing to end). */
+    async function endSignedInSession(request, token) {
+        const found = await logoutStep(request, "findRefreshTokenByHash", () => store.findRefreshTokenByHash(hashRefreshToken(token)));
+        if (!found.ok)
+            return false;
+        const stored = found.value;
+        if (!stored)
+            return true;
+        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;
+    }
 };
 export const flytedeskAuth = fp(flytedeskAuthPlugin, {
     name: "@flytedesk/app-kit/auth",