@flytedesk/app-kit 0.7.1 → 1.0.0

package/dist/auth/index.js

@@ -5,10 +5,26 @@
  * src/{routes/auth.ts,lib/flytedeskId.ts,plugins/auth.ts} so client id/secret, issuer,
  * redirect URI, and app id are config instead of hardcoded to one app.
  *
+ * This module (`@flytedesk/app-kit/auth`) is the standalone surface: types, the OIDC
+ * client, PKCE/token/error helpers, and the `requireAuth`/`requirePermission` guards —
+ * everything that does NOT need Fastify's `FastifyRequest` ambient-augmented with
+ * `authUser`. The plugin itself (`flytedeskAuth`, and the `declare module "fastify"`
+ * augmentation that comes with registering it) lives at the separate subpath
+ * `@flytedesk/app-kit/auth/plugin` (AK-14, gap 6): TypeScript applies a `declare module`
+ * augmentation program-wide the instant ANY file importing it is part of the
+ * compilation, even transitively — so as long as `flytedeskAuth` was re-exported from
+ * here too, importing just `generatePkce`/`randomState`/`signAccessToken` from this
+ * module forced the augmentation (and its `AuthedUser` shape) onto a consumer's WHOLE
+ * program, with no way to opt out — including a consumer with its own, differently
+ * shaped `request.authUser` who never even registers this plugin (`TS2717: Subsequent
+ * property declarations must have the same type`). Splitting the plugin into its own
+ * subpath means the augmentation only applies to a program that actually imports it.
+ *
  * Usage:
  *
  *   import Fastify from "fastify";
- *   import { flytedeskAuth, requireAuth, requirePermission } from "@flytedesk/app-kit/auth";
+ *   import { flytedeskAuth } from "@flytedesk/app-kit/auth/plugin";
+ *   import { requireAuth, requirePermission } from "@flytedesk/app-kit/auth";
  *
  *   const app = Fastify();
  *   await app.register(flytedeskAuth, {
@@ -26,10 +42,10 @@
  *
  *   app.get("/me", { preHandler: requireAuth }, async (request) => request.authUser);
  */
-export { flytedeskAuth } from "./plugin.js";
 export { requireAuth, requirePermission } from "./guards.js";
-export { createOidcClient } from "./oidc-client.js";
-export { IdpError, IdpUnavailableError, IdpAccessRevokedError, AuthStoreError, OidcHttpError, classifyIdpError, } from "./errors.js";
+export { createOidcClient, DEFAULT_OIDC_SCOPES, DEFAULT_TOKEN_REQUEST_TIMEOUT_MS } from "./oidc-client.js";
+export { AUTH_REQUEST_DEADLINE_MS, AUTH_ROUTE_PREFIX, AUTH_ROUTE_SEGMENTS, authRoutePath, SILENT_AUTH_MESSAGE_SOURCE, } from "./shared-types.js";
+export { IdpError, IdpUnavailableError, IdpTimeoutError, IdpAccessRevokedError, AuthStoreError, OidcHttpError, classifyIdpError, } from "./errors.js";
 export { generatePkce, randomState } from "./pkce.js";
 export { generateRefreshToken, hashRefreshToken, signAccessToken, verifyAccessToken, } from "./tokens.js";
 //# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAsB7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAIpD,OAAO,EACL,QAAQ,EACR,mBAAmB,EACnB,qBAAqB,EACrB,cAAc,EACd,aAAa,EACb,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,YAAY,EAAE,WAAW,EAAiB,MAAM,WAAW,CAAC;AAErE,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,iBAAiB,GAElB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAuB7D,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,gCAAgC,EAAE,MAAM,kBAAkB,CAAC;AAG3G,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACb,0BAA0B,GAE3B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,QAAQ,EACR,mBAAmB,EACnB,eAAe,EACf,qBAAqB,EACrB,cAAc,EACd,aAAa,EACb,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,YAAY,EAAE,WAAW,EAAiB,MAAM,WAAW,CAAC;AAErE,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,iBAAiB,GAElB,MAAM,aAAa,CAAC"}

package/dist/auth/oidc-client.d.ts

@@ -1,10 +1,34 @@
 import type { AppSwitcherEntry } from "./shared-types.js";
 import type { UserinfoClaims } from "./types.js";
+/**
+ * Requested by default (AK-14, gap 1): without `offline_access`, flytedesk-id's
+ * oidc-provider never issues a refresh token, and every session dies the moment its
+ * ~1h IdP-side access token expires — a previously-shipped production bug (see
+ * media-planner's now-superseded `lib/flytedeskId.ts` doc comment on `buildAuthorizeUrl`).
+ * `offline_access` is ON by default here because a session that dies after an hour is
+ * almost never what a consuming app actually wants; a consumer that genuinely needs a
+ * narrower grant can override via `FlytedeskAuthOptions.scopes`/`OidcClientOptions.scopes`.
+ */
+export declare const DEFAULT_OIDC_SCOPES: readonly ["openid", "email", "profile", "offline_access"];
+/** Sane default for every flytedesk-id `/token` call (AK-14, gap 5) — matches
+ *  media-planner's `IDP_TOKEN_TIMEOUT_MS`, which `services/idpSession.ts` there sizes a
+ *  DB transaction + advisory lock around specifically so it can never be held open while
+ *  a `/token` call is still in flight. Configurable via
+ *  `OidcClientOptions.tokenRequestTimeoutMs`. */
+export declare const DEFAULT_TOKEN_REQUEST_TIMEOUT_MS = 5000;
 export interface OidcClientOptions {
     issuer: string;
     clientId: string;
     clientSecret: string;
     redirectUri: string;
+    /** OAuth scopes requested by `buildAuthorizeUrl`. Default `DEFAULT_OIDC_SCOPES`
+     *  (includes `offline_access` — see that constant's doc comment). */
+    scopes?: string[];
+    /** Bounds every `/token` call (`exchangeCodeForTokens`, `refreshIdpTokens`) via
+     *  `AbortSignal.timeout`. Default `DEFAULT_TOKEN_REQUEST_TIMEOUT_MS`. A hung
+     *  flytedesk-id response rejects with `IdpTimeoutError` instead of hanging the
+     *  caller (and, transitively, whatever lock/transaction it's inside) indefinitely. */
+    tokenRequestTimeoutMs?: number;
 }
 export interface IdpTokenResponse {
     access_token: string;
@@ -28,9 +52,14 @@ export interface IdpAuthorization {
 }
 export type { AppSwitcherEntry };
 export interface OidcClient {
+    /** `prompt` is passed straight through to flytedesk-id's `/auth` endpoint —
+     *  `"none"` (OIDC Core 3.1.2.1) is what drives silent (hidden-iframe) re-auth; see
+     *  `../plugin.ts`'s `GET {routePrefix}/login` and `./client/silentAuth.ts`. Omitted
+     *  entirely (not sent as an empty string) when not given. */
     buildAuthorizeUrl(opts: {
         state: string;
         challenge: string;
+        prompt?: string;
     }): string;
     exchangeCodeForTokens(code: string, verifier: string): Promise<IdpTokenResponse>;
     refreshIdpTokens(refreshToken: string): Promise<IdpTokenResponse>;

package/dist/auth/oidc-client.js

@@ -1,5 +1,21 @@
 import { createRemoteJWKSet, jwtVerify } from "jose";
-import { OidcHttpError } from "./errors.js";
+import { IdpTimeoutError, IdpUnavailableError, OidcHttpError } from "./errors.js";
+/**
+ * Requested by default (AK-14, gap 1): without `offline_access`, flytedesk-id's
+ * oidc-provider never issues a refresh token, and every session dies the moment its
+ * ~1h IdP-side access token expires — a previously-shipped production bug (see
+ * media-planner's now-superseded `lib/flytedeskId.ts` doc comment on `buildAuthorizeUrl`).
+ * `offline_access` is ON by default here because a session that dies after an hour is
+ * almost never what a consuming app actually wants; a consumer that genuinely needs a
+ * narrower grant can override via `FlytedeskAuthOptions.scopes`/`OidcClientOptions.scopes`.
+ */
+export const DEFAULT_OIDC_SCOPES = ["openid", "email", "profile", "offline_access"];
+/** Sane default for every flytedesk-id `/token` call (AK-14, gap 5) — matches
+ *  media-planner's `IDP_TOKEN_TIMEOUT_MS`, which `services/idpSession.ts` there sizes a
+ *  DB transaction + advisory lock around specifically so it can never be held open while
+ *  a `/token` call is still in flight. Configurable via
+ *  `OidcClientOptions.tokenRequestTimeoutMs`. */
+export const DEFAULT_TOKEN_REQUEST_TIMEOUT_MS = 5_000;
 /**
  * One instance per FlytedeskAuthOptions (i.e. per plugin registration), not a module
  * singleton — keeps the JWKS/discovery caches below scoped to one issuer/client pair
@@ -23,15 +39,35 @@ export function createOidcClient(opts) {
         const clientSecret = encodeURIComponent(opts.clientSecret);
         return "Basic " + Buffer.from(`${clientId}:${clientSecret}`).toString("base64");
     }
+    const tokenRequestTimeoutMs = opts.tokenRequestTimeoutMs ?? DEFAULT_TOKEN_REQUEST_TIMEOUT_MS;
+    /**
+     * Bounded by `AbortSignal.timeout` (AK-14, gap 5): unbounded before this, a hung
+     * flytedesk-id `/token` response could hold open whatever the caller wraps this in —
+     * for a consumer following media-planner's model (`services/idpSession.ts`), a
+     * Postgres transaction + advisory lock sized around exactly this bound. A timeout
+     * throws the more specific `IdpTimeoutError`; any other network failure (DNS, refused
+     * connection, ...) is classified as `IdpUnavailableError` rather than propagating an
+     * unclassified error — both are typed, neither is swallowed.
+     */
     async function tokenRequest(body) {
-        const res = await fetch(issuerUrl("/token"), {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/x-www-form-urlencoded",
-                Authorization: basicAuthHeader(),
-            },
-            body: new URLSearchParams(body).toString(),
-        });
+        let res;
+        try {
+            res = await fetch(issuerUrl("/token"), {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    Authorization: basicAuthHeader(),
+                },
+                body: new URLSearchParams(body).toString(),
+                signal: AbortSignal.timeout(tokenRequestTimeoutMs),
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError")) {
+                throw new IdpTimeoutError(`flytedesk-id /token did not respond within ${tokenRequestTimeoutMs}ms`, err);
+            }
+            throw new IdpUnavailableError(`flytedesk-id /token request failed: ${err instanceof Error ? err.message : String(err)}`, err);
+        }
         if (!res.ok) {
             const text = await res.text().catch(() => "");
             throw new OidcHttpError(`flytedesk-id /token returned ${res.status}: ${text}`, res.status);
@@ -52,16 +88,19 @@ export function createOidcClient(opts) {
         });
         return discoveryCache;
     }
+    const scope = (opts.scopes ?? DEFAULT_OIDC_SCOPES).join(" ");
     return {
-        buildAuthorizeUrl({ state, challenge }) {
+        buildAuthorizeUrl({ state, challenge, prompt }) {
             const url = new URL(issuerUrl("/auth"));
             url.searchParams.set("client_id", opts.clientId);
             url.searchParams.set("redirect_uri", opts.redirectUri);
             url.searchParams.set("response_type", "code");
-            url.searchParams.set("scope", "openid email profile");
+            url.searchParams.set("scope", scope);
             url.searchParams.set("code_challenge", challenge);
             url.searchParams.set("code_challenge_method", "S256");
             url.searchParams.set("state", state);
+            if (prompt)
+                url.searchParams.set("prompt", prompt);
             return url.toString();
         },
         /** Authorization Code + PKCE exchange — the one moment this app's client_secret is used. */

package/dist/auth/oidc-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"oidc-client.js","sourceRoot":"","sources":["../../src/auth/oidc-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"oidc-client.js","sourceRoot":"","sources":["../../src/auth/oidc-client.ts"],"names":[],"mappings":"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"}

package/dist/auth/plugin.js

@@ -4,8 +4,8 @@ import fastifyCookie from "@fastify/cookie";
 import { AuthStoreError, IdpAccessRevokedError, 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, } from "./shared-types.js";
 import { generateRefreshToken, hashRefreshToken, signAccessToken, verifyAccessToken } from "./tokens.js";
-const DEFAULT_ROUTE_PREFIX = "/auth";
 const DEFAULT_ACCESS_TOKEN_TTL_SECONDS = 900;
 const DEFAULT_REFRESH_TOKEN_TTL_SECONDS = 2_592_000;
 const DEFAULT_LOGIN_ATTEMPT_TTL_SECONDS = 600;
@@ -38,10 +38,19 @@ function assertRequiredOptions(options) {
 }
 const flytedeskAuthPlugin = async (fastify, options) => {
     assertRequiredOptions(options);
-    const routePrefix = options.routePrefix ?? DEFAULT_ROUTE_PREFIX;
+    const routePrefix = options.routePrefix ?? AUTH_ROUTE_PREFIX;
     const accessTokenTtlSeconds = options.accessTokenTtlSeconds ?? DEFAULT_ACCESS_TOKEN_TTL_SECONDS;
     const refreshTokenTtlSeconds = options.refreshTokenTtlSeconds ?? DEFAULT_REFRESH_TOKEN_TTL_SECONDS;
     const loginAttemptTtlSeconds = options.loginAttemptTtlSeconds ?? DEFAULT_LOGIN_ATTEMPT_TTL_SECONDS;
+    // 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;
     const store = options.store;
     if (options.authorizationCacheTtlMs) {
         fastify.log.warn({ authorizationCacheTtlMs: options.authorizationCacheTtlMs }, "@flytedesk/app-kit/auth: authorizationCacheTtlMs is set — flytedesk-id authorization " +
@@ -53,6 +62,8 @@ const flytedeskAuthPlugin = async (fastify, options) => {
         clientId: options.clientId,
         clientSecret: options.clientSecret,
         redirectUri: options.redirectUri,
+        scopes: options.scopes,
+        tokenRequestTimeoutMs: options.tokenRequestTimeoutMs,
     });
     await fastify.register(fastifyCookie, { secret: options.cookieSecret });
     fastify.decorateRequest("authUser", undefined);
@@ -83,6 +94,27 @@ const flytedeskAuthPlugin = async (fastify, options) => {
             maxAge: maxAgeSeconds,
         };
     }
+    /**
+     * 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`.
+     */
+    function sendSilentResult(reply, status, detail) {
+        const message = {
+            source: SILENT_AUTH_MESSAGE_SOURCE,
+            status,
+            detail: detail ?? null,
+        };
+        return reply
+            .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>`);
+    }
     const authorizationCache = new Map();
     const EXPIRY_SKEW_MS = 5_000;
     /**
@@ -177,7 +209,7 @@ const flytedeskAuthPlugin = async (fastify, options) => {
         // never collide across apps in its catalog — strip the prefix so the consuming
         // app's own permission checks don't have to know about it.
         const prefix = `${options.appId}:`;
-        return {
+        const user = {
             id: session.subject,
             email: session.email,
             name: session.name,
@@ -185,6 +217,26 @@ const flytedeskAuthPlugin = async (fastify, options) => {
             roles: authorization.roles,
             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".
+        if (options.onAuthorizeUser) {
+            let authorized;
+            try {
+                authorized = await options.onAuthorizeUser(user, request);
+            }
+            catch (err) {
+                request.log.error({ err, sid: claims.sid }, "@flytedesk/app-kit/auth: onAuthorizeUser threw — treating the session as rejected");
+                return undefined;
+            }
+            if (!authorized)
+                return undefined;
+            return authorized;
+        }
+        return user;
     }
     // onRequest, not preHandler: this needs to run before any route-level preHandler
     // (requireAuth/requirePermission included) so request.authUser is already resolved
@@ -215,6 +267,8 @@ const flytedeskAuthPlugin = async (fastify, options) => {
             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);
         reply.setCookie(refreshCookieName, refreshToken, refreshCookieOptions(refreshTokenTtlSeconds));
@@ -222,15 +276,28 @@ const flytedeskAuthPlugin = async (fastify, options) => {
     }
     /**
      * GET {routePrefix}/login — starts the flytedesk-id sign-in. A plain redirect meant
-     * to be hit via full-page navigation, not fetch/XHR. Generates a PKCE verifier/
-     * challenge (S256 — flytedesk-id makes PKCE mandatory) and a CSRF `state`, stashes
-     * both in a short-lived signed cookie tied to this browser, then redirects to
-     * flytedesk-id's own /auth endpoint.
+     * 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.
+     *
+     * `?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.
      */
-    fastify.get(`${routePrefix}/login`, async (request, reply) => {
+    fastify.get(authRoutePath(routePrefix, "login"), async (request, reply) => {
         const { verifier, challenge } = generatePkce();
         const state = randomState();
-        reply.setCookie(loginCookieName, JSON.stringify({ verifier, state }), {
+        const prompt = request.query.prompt;
+        const silent = prompt === "none";
+        reply.setCookie(loginCookieName, JSON.stringify({ verifier, state, silent }), {
             httpOnly: true,
             sameSite: "lax",
             secure: options.secureCookies,
@@ -238,7 +305,7 @@ const flytedeskAuthPlugin = async (fastify, options) => {
             maxAge: loginAttemptTtlSeconds,
             signed: true,
         });
-        return reply.redirect(oidc.buildAuthorizeUrl({ state, challenge }));
+        return reply.redirect(oidc.buildAuthorizeUrl({ state, challenge, prompt }));
     });
     /**
      * GET {routePrefix}/callback — flytedesk-id's redirect_uri for this client. Validates
@@ -247,37 +314,45 @@ const flytedeskAuthPlugin = async (fastify, options) => {
      * id_token's signature via flytedesk-id's JWKS, fetches profile claims from
      * userinfo, then mints this service's own session.
      */
-    fastify.get(`${routePrefix}/callback`, async (request, reply) => {
+    fastify.get(authRoutePath(routePrefix, "callback"), async (request, reply) => {
         const { code, state, error } = request.query;
         const raw = request.cookies[loginCookieName];
         reply.clearCookie(loginCookieName, { path: cookiePath });
-        if (error) {
-            return reply
-                .code(400)
-                .send({ error: `flytedesk-id sign-in failed: ${error}`, code: "idp_error" });
+        // 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).
+        let stash;
+        if (raw) {
+            const unsigned = request.unsignCookie(raw);
+            if (unsigned.valid && unsigned.value) {
+                try {
+                    stash = JSON.parse(unsigned.value);
+                }
+                catch {
+                    stash = undefined;
+                }
+            }
         }
-        if (!code || !state || !raw) {
-            return reply.code(400).send({
-                error: "Missing code/state, or the login attempt expired",
-                code: "invalid_callback",
-            });
+        const silent = stash?.silent === true;
+        function fail(status, code, message) {
+            if (silent)
+                return sendSilentResult(reply, "error", code);
+            return reply.code(status).send({ error: message, code });
         }
-        const unsigned = request.unsignCookie(raw);
-        if (!unsigned.valid || !unsigned.value) {
-            return reply.code(400).send({
-                error: "Login attempt cookie failed verification",
-                code: "invalid_login_cookie",
-            });
+        if (error) {
+            return fail(400, error, `flytedesk-id sign-in failed: ${error}`);
         }
-        let stash;
-        try {
-            stash = JSON.parse(unsigned.value);
+        if (!code || !state || !raw) {
+            return fail(400, "invalid_callback", "Missing code/state, or the login attempt expired");
         }
-        catch {
-            return reply.code(400).send({ error: "Corrupt login attempt", code: "invalid_login_cookie" });
+        if (!stash) {
+            return fail(400, "invalid_login_cookie", "Login attempt cookie failed verification");
         }
         if (stash.state !== state) {
-            return reply.code(400).send({ error: "State mismatch", code: "invalid_state" });
+            return fail(400, "invalid_state", "State mismatch");
         }
         try {
             const tokens = await oidc.exchangeCodeForTokens(code, stash.verifier);
@@ -286,16 +361,10 @@ const flytedeskAuthPlugin = async (fastify, options) => {
             const idToken = await oidc.verifyIdToken(tokens.id_token);
             const profile = await oidc.fetchUserinfo(tokens.access_token);
             if (profile.sub !== idToken.sub) {
-                return reply.code(401).send({
-                    error: "flytedesk-id id_token/userinfo subject mismatch",
-                    code: "subject_mismatch",
-                });
+                return fail(401, "subject_mismatch", "flytedesk-id id_token/userinfo subject mismatch");
             }
             if (!profile.emailVerified) {
-                return reply.code(401).send({
-                    error: "flytedesk-id account email is not verified",
-                    code: "email_not_verified",
-                });
+                return fail(401, "email_not_verified", "flytedesk-id account email is not verified");
             }
             if (options.onSignIn) {
                 await options.onSignIn(profile, request);
@@ -313,28 +382,63 @@ const flytedeskAuthPlugin = async (fastify, options) => {
             // only ever revokes the chain descended from one login, never sibling sessions.
             const familyId = randomUUID();
             await issueSession(request, reply, profile.sub, idpSession.id, familyId);
+            if (silent) {
+                // No top-level navigation at all — issueSession() 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);
         }
         catch (err) {
             request.log.error({ err }, "flytedesk-id callback failed");
-            return reply
-                .code(502)
-                .send({ error: "Sign-in with flytedesk-id failed", code: "idp_exchange_failed" });
+            return fail(502, "idp_exchange_failed", "Sign-in with flytedesk-id failed");
         }
     });
+    /** 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. */
+    function rejectRefresh(reply, { clearCookie }) {
+        if (clearCookie)
+            reply.clearCookie(refreshCookieName, { path: cookiePath });
+        return reply.code(401).send({ error: "Refresh token expired or revoked", code: "unauthenticated" });
+    }
     /**
      * POST {routePrefix}/refresh — no body, reads the refresh cookie. Rotates it on every
-     * successful call. A hash match on a row that's already revoked means this exact
-     * token was replayed (its legitimate rotation already consumed it) — that's treated
-     * as a security event: the whole family is revoked, not just this row, since every
-     * token downstream of the replayed one must be assumed compromised too.
+     * successful call.
      *
-     * The claim (store.claimRefreshTokenForRotation) happens BEFORE the expiry check and
-     * is what actually detects reuse — not a `stored.revokedAt` read, which would leave a
-     * window between two concurrent requests both observing "not yet revoked" before
-     * either write lands. See that method's doc comment in ./types.ts.
+     * 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:
+     *
+     *  - 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`).
+     *
+     * 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.
      */
-    fastify.post(`${routePrefix}/refresh`, async (request, 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" });
@@ -345,25 +449,36 @@ const flytedeskAuthPlugin = async (fastify, options) => {
             reply.clearCookie(refreshCookieName, { path: cookiePath });
             return reply.code(401).send({ error: "Refresh token not recognized", code: "unauthenticated" });
         }
-        const claimed = await store.claimRefreshTokenForRotation(stored.id);
-        if (!claimed) {
-            // Already revoked by the time this call's UPDATE ran — either a genuine prior
-            // revocation or a concurrent /refresh call that won the race. Both are reuse.
-            request.log.warn({ familyId: stored.familyId, userId: stored.userId }, "@flytedesk/app-kit/auth: refresh token reuse detected — revoking token family");
+        if (stored.revokedAt) {
+            const sinceRevokedMs = Date.now() - stored.revokedAt.getTime();
+            if (stored.rotated && sinceRevokedMs < refreshReuseGraceMs) {
+                return rejectRefresh(reply, { clearCookie: false });
+            }
+            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);
             reply.clearCookie(refreshCookieName, { path: cookiePath });
             return reply.code(401).send({ error: "Refresh token reuse detected", code: "token_reuse_detected" });
         }
         if (stored.expiresAt < new Date()) {
-            // Claimed (now revoked, so it can never be presented again) but past its TTL —
-            // an expired token, not a reuse event.
             reply.clearCookie(refreshCookieName, { path: cookiePath });
             return reply.code(401).send({ error: "Refresh token expired", 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.
+        // 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({
@@ -375,6 +490,7 @@ const flytedeskAuthPlugin = async (fastify, options) => {
             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));
@@ -391,7 +507,7 @@ const flytedeskAuthPlugin = async (fastify, options) => {
      * no token). Every upstream failure is mapped to a typed, logged error: never an
      * unmapped 500 carrying flytedesk-id's raw response text.
      */
-    fastify.get(`${routePrefix}/apps`, async (request, reply) => {
+    fastify.get(authRoutePath(routePrefix, "apps"), async (request, reply) => {
         if (!request.authUser) {
             return reply.code(401).send({ error: "Authentication required", code: "unauthenticated" });
         }
@@ -433,6 +549,22 @@ const flytedeskAuthPlugin = async (fastify, options) => {
             return reply.code(502).send({ error: "flytedesk-id is unavailable", code: "idp_unavailable" });
         }
     });
+    /**
+     * GET {routePrefix}/me — the signed-in user, with roles/permissions from the SAME live
+     * 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
+     * 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.
+     */
+    fastify.get(authRoutePath(routePrefix, "me"), async (request, reply) => {
+        if (!request.authUser) {
+            return reply.code(401).send({ error: "Authentication required", code: "unauthenticated" });
+        }
+        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
@@ -441,7 +573,7 @@ const flytedeskAuthPlugin = async (fastify, options) => {
      * 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.
      */
-    fastify.post(`${routePrefix}/logout`, async (request, reply) => {
+    fastify.post(authRoutePath(routePrefix, "logout"), async (request, reply) => {
         const token = request.cookies[refreshCookieName];
         if (token) {
             const hash = hashRefreshToken(token);