chrome: brandIcons() — derive Next.js favicon metadata from Brand

Every app that imports the kit was shipping a /favicon.ico 404
because none of them wired up Next.js's metadata.icons. This adds
a tiny helper so an app only has to:

  export const metadata: Metadata = {
    title: brand.product,
    icons: brandIcons(brand),
  };

brandIcons() returns icon/shortcut/apple entries pointing at
brand.faviconUrl (new optional field, defaults to brand.logoUrl).
MIME type inferred from the URL extension (svg/png/ico).

Brand gains the optional faviconUrl field. Existing apps that just
pass logoUrl keep working — they'll now render the logo as the
favicon by default. Apps that want a separate icon set
faviconUrl explicitly.

First consumer: gscSounds layout — verified /favicon.ico now
serves the proper icon and /icon.svg works too.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsc/web-kit",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "GSC web app skeleton — layout, auth, data, forms, feedback, navigation, chrome. Built on @limitless/ui. Drop into a Next.js app and just write pages.",
   "license": "MIT",
   "type": "module",
@@ -65,6 +65,14 @@
       "types": "./dist/api/index.d.ts",
       "import": "./dist/api/index.js"
     },
+    "./i18n": {
+      "types": "./dist/i18n/index.d.ts",
+      "import": "./dist/i18n/index.js"
+    },
+    "./i18n/server": {
+      "types": "./dist/i18n/server.d.ts",
+      "import": "./dist/i18n/server.js"
+    },
     "./utils": {
       "types": "./dist/utils/index.d.ts",
       "import": "./dist/utils/index.js"

src/auth/SessionExpirationGuard.tsx

@@ -0,0 +1,50 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import { useSession, signIn } from "next-auth/react";
+
+import type { SessionUser } from "./types";
+
+/**
+ * Drop-in client component that re-triggers Keycloak sign-in when the
+ * kit's server-side refresh flow gives up (`session.user.error` set to
+ * `RefreshAccessTokenError` or `RefreshTokenMissing`).
+ *
+ * Without this, a UI tab left open past the Keycloak SSO session lifetime
+ * holds a stale `accessToken`: the middleware sees a cookie, `requireAuth`
+ * sees an `accessToken` string, and the user only finds out things are
+ * broken when a downstream API returns 401. Mount this inside a
+ * `<SessionProvider>` (typically alongside other providers in the locale
+ * root) so the session refetch interval surfaces the error within minutes.
+ *
+ * Renders nothing.
+ */
+export function SessionExpirationGuard() {
+  const { data: session } = useSession();
+  const error = (session?.user as Partial<SessionUser> | undefined)?.error;
+  // Guard against React's StrictMode double-invoke + the brief window
+  // between calling signIn and the page navigating away.
+  const firedRef = useRef(false);
+
+  useEffect(() => {
+    if (!error || firedRef.current) return;
+    if (
+      error !== "RefreshAccessTokenError" &&
+      error !== "RefreshTokenMissing"
+    ) {
+      return;
+    }
+    firedRef.current = true;
+    const callbackUrl =
+      typeof window !== "undefined"
+        ? window.location.pathname + window.location.search
+        : "/";
+    // signIn() POSTs the CSRF-protected provider endpoint, which then
+    // initiates a fresh OIDC flow; the stale session cookie is replaced
+    // atomically when the flow completes. Keycloak's own SSO cookie may
+    // still log the user in transparently if it hasn't also expired.
+    void signIn("keycloak", { callbackUrl });
+  }, [error]);
+
+  return null;
+}

src/auth/index.ts

@@ -7,6 +7,7 @@
  */
 
 export type { SessionUser } from "./types";
+export { SessionExpirationGuard } from "./SessionExpirationGuard";
 
 /**
  * Client-side hard navigation to the sign-in endpoint. Use when a

src/auth/server.ts

@@ -266,7 +266,11 @@ export function createAuth(opts: CreateAuthOptions): AuthBundle {
   async function requireAuth(): Promise<SessionUser> {
     const session = await na.auth();
     const user = (session as unknown as { user?: SessionUser } | null)?.user;
-    if (!user || !user.accessToken) {
+    // `user.error` is set when the kit's silent refresh failed (refresh
+    // token expired/revoked or Keycloak rejected the exchange). The
+    // session cookie is still present, so the middleware won't catch
+    // this — bouncing here is what forces a fresh sign-in flow.
+    if (!user || !user.accessToken || user.error) {
       redirect(signInPath);
     }
     return user;

src/chrome/AdminShell.tsx

@@ -100,17 +100,21 @@ function normalizeIconClass(iconClass: string | null | undefined) {
 }
 
 /**
- * Prepend `/{locale}` to internal absolute paths. Leaves external URLs
- * (http(s)://…), already-prefixed paths, and the "#" sentinel alone.
- * Menu-item URLs in the DB are stored locale-agnostic (e.g. `/contacts`);
- * routing configs like `localePrefix: 'always'` require `/{locale}/contacts`.
+ * Originally prepended `/{locale}` to internal URLs for apps using
+ * next-intl's `localePrefix: 'always'` (i.e. with a `[locale]` route
+ * segment). None of the kit's consumers (gscAdmin, gscMy, gscCRM,
+ * gscSupport, …) currently use that routing pattern — they resolve
+ * the locale per-request via cookie/Accept-Language and serve pages
+ * at unprefixed paths (e.g. `/dashboard`, not `/de/dashboard`). The
+ * prefix-prepend behaviour produced 404s for those apps, so this is
+ * now a no-op.
+ *
+ * If a future consumer DOES adopt `[locale]` routing, gate the
+ * prefixing behind an `AdminShellProps.localePrefix` flag rather than
+ * reverting this unconditionally.
  */
-function withLocale(url: string, locale: string): string {
-  if (!url || url === "#") return url;
-  if (/^[a-z]+:\/\//i.test(url)) return url;
-  if (!url.startsWith("/")) return url;
-  if (url === `/${locale}` || url.startsWith(`/${locale}/`)) return url;
-  return `/${locale}${url}`;
+function withLocale(url: string, _locale: string): string {
+  return url;
 }
 
 /** Strip a leading `/{locale}` segment so breadcrumbs/titles work on the app-level path. */
@@ -208,6 +212,8 @@ export function AdminShell({
   features,
   slots,
   onSignOut,
+  signoutPath,
+  myProfileUrl,
   labels: labelOverrides,
   children,
 }: AdminShellProps) {
@@ -328,6 +334,8 @@ export function AdminShell({
         setShowActivityModal={setShowActivityModal}
         onOpenChat={feat.chat ? () => setShowChatOverlay((open) => !open) : undefined}
         onSignOut={onSignOut}
+        signoutPath={signoutPath}
+        myProfileUrl={myProfileUrl}
       />
 
       {feat.subbar && (
@@ -418,6 +426,8 @@ function AdminNavbar({
   setShowActivityModal,
   onOpenChat,
   onSignOut,
+  signoutPath,
+  myProfileUrl,
 }: {
   feat: Required<ChromeFeatures>;
   slot: ChromeSlots;
@@ -435,6 +445,8 @@ function AdminNavbar({
   setShowActivityModal: (show: boolean) => void;
   onOpenChat?: () => void;
   onSignOut?: () => void | Promise<void>;
+  signoutPath?: string;
+  myProfileUrl?: string | null;
 }) {
   const [showNavMenu, setShowNavMenu] = useState(false);
 
@@ -539,6 +551,31 @@ function AdminNavbar({
                 transform: "translate3d(0px, 44px, 0px)",
               }}
             >
+              {(() => {
+                // gscMy lives at a fixed cross-app URL; default points there.
+                // Pass `myProfileUrl={null}` to omit (e.g. gscMy itself, which
+                // links to its own /profile via topbarMenu).
+                const profileHref =
+                  myProfileUrl === undefined
+                    ? "https://my.gosec.internal/profile"
+                    : myProfileUrl;
+                if (!profileHref) return null;
+                const isExternal = /^https?:\/\//.test(profileHref);
+                return isExternal ? (
+                  <a href={profileHref} className="dropdown-item">
+                    <i className="ph-user-circle me-2"></i>
+                    {labels.myProfile}
+                  </a>
+                ) : (
+                  <Link
+                    href={withLocale(profileHref, locale)}
+                    className="dropdown-item"
+                  >
+                    <i className="ph-user-circle me-2"></i>
+                    {labels.myProfile}
+                  </Link>
+                );
+              })()}
               {topbarMenu.map((menuItem) => (
                 <Link
                   href={withLocale(menuItem.url, locale)}
@@ -551,7 +588,11 @@ function AdminNavbar({
                   {tMenu(normalizeTranslationKey(menuItem.translationKey))}
                 </Link>
               ))}
-              <LogoutButton label={labels.logout} onSignOut={onSignOut} />
+              <LogoutButton
+                label={labels.logout}
+                signoutPath={signoutPath}
+                onSignOut={onSignOut}
+              />
             </div>
           </li>
         </ul>

src/chrome/LogoutButton.tsx

@@ -1,46 +1,45 @@
 "use client";
 
-import { signOut } from "next-auth/react";
-
 /**
- * Default flow (shared org Keycloak):
- *   1. GET /api/auth/logout — host app returns { logoutUrl } pointing at
- *      Keycloak's end_session endpoint (id_token_hint included).
- *   2. next-auth signOut() locally — fires events.signOut for backchannel
- *      revocation; redirect:false so we control the navigation.
- *   3. Navigate to logoutUrl — kills the SSO cookie at Keycloak.
+ * Default flow: a plain anchor to `/api/auth/signout` (overridable via
+ * the `signoutPath` prop). The route handler runs RP-initiated logout
+ * in a single redirect — kills the NextAuth cookie, ends the Keycloak
+ * SSO session, lands on the app's signed-out page.
  *
- * Apps without /api/auth/logout (or that need a different flow) pass
- * `onSignOut` to fully replace this behavior.
+ * Apps with a different shape (no `/api/auth/signout`, need to fire
+ * custom telemetry, etc.) pass `onSignOut` to replace the navigation
+ * with a button + custom handler.
  */
 type LogoutButtonProps = {
   label: string;
+  signoutPath?: string;
   onSignOut?: () => void | Promise<void>;
 };
 
-export function LogoutButton({ label, onSignOut }: LogoutButtonProps) {
-  const handleLogout = async () => {
-    if (onSignOut) {
-      await onSignOut();
-      return;
-    }
-
-    let logoutUrl = "/logged-out";
-    try {
-      const res = await fetch("/api/auth/logout");
-      const body = await res.json();
-      if (body?.logoutUrl) logoutUrl = body.logoutUrl;
-    } catch {
-      // fall through with local-only logout
-    }
-    await signOut({ redirect: false });
-    window.location.href = logoutUrl;
-  };
+export function LogoutButton({
+  label,
+  signoutPath = "/api/auth/signout",
+  onSignOut,
+}: LogoutButtonProps) {
+  if (onSignOut) {
+    return (
+      <button
+        type="button"
+        onClick={() => {
+          void onSignOut();
+        }}
+        className="dropdown-item"
+      >
+        <i className="ph-sign-out me-2"></i>
+        {label}
+      </button>
+    );
+  }
 
   return (
-    <button type="button" onClick={handleLogout} className="dropdown-item">
+    <a href={signoutPath} className="dropdown-item">
       <i className="ph-sign-out me-2"></i>
       {label}
-    </button>
+    </a>
   );
 }

src/chrome/brandIcons.ts

@@ -0,0 +1,37 @@
+// Returns a Next.js Metadata `icons` object derived from a Brand.
+// Apps drop this into their root layout's `metadata` export to ship
+// the brand logo as the favicon — fixes the "favicon 404" every
+// consumer of the kit was shipping with.
+//
+//   import type { Metadata } from "next";
+//   import { brandIcons } from "@gsc/web-kit/chrome";
+//   import { brand } from "@/config/brand";
+//
+//   export const metadata: Metadata = {
+//     title: brand.product,
+//     icons: brandIcons(brand),
+//   };
+
+import type { Brand } from "./types";
+
+interface BrandMetaIcons {
+  icon: { url: string; type?: string }[];
+  shortcut?: { url: string; type?: string }[];
+  apple?: { url: string; type?: string }[];
+}
+
+export function brandIcons(brand: Brand): BrandMetaIcons {
+  const url = brand.faviconUrl ?? brand.logoUrl;
+  // Heuristic: trust the file extension to set the MIME type. Most
+  // brand logos in the GoSec assets bucket are SVG.
+  const type =
+    /\.svg(\?|$)/i.test(url) ? "image/svg+xml" :
+    /\.png(\?|$)/i.test(url) ? "image/png" :
+    /\.ico(\?|$)/i.test(url) ? "image/x-icon" :
+    undefined;
+  return {
+    icon: [{ url, ...(type ? { type } : {}) }],
+    shortcut: [{ url }],
+    apple: [{ url }],
+  };
+}

src/chrome/index.ts

@@ -11,6 +11,7 @@ export {
   type CustomerOption,
 } from "./header";
 export { useChromeLabels, DEFAULT_CHROME_LABELS } from "./labels";
+export { brandIcons } from "./brandIcons";
 export type {
   AdminShellProps,
   ActivityFeedItem,

src/chrome/labels.ts

@@ -15,6 +15,7 @@ export const DEFAULT_CHROME_LABELS: ChromeLabels = {
   settings: "Settings",
   allSettings: "All Settings",
   logout: "Logout",
+  myProfile: "My Profile",
   docs: "Docs",
   browseApps: "Browse apps",
   viewAll: "View all",

src/chrome/types.ts

@@ -61,6 +61,7 @@ export type Brand = {
   product: string;             // "GoSec CRM"
   logoUrl: string;             // full navbar logo
   logoSmallUrl?: string;       // optional compact logo
+  faviconUrl?: string;         // optional favicon override (defaults to logoUrl)
   websiteUrl: string;          // footer brand link
   supportUrl: string;          // subbar Support + footer Support link
   docsUrl: string;             // footer docs link
@@ -132,6 +133,7 @@ export type ChromeLabels = {
   settings: string;              // subbar "Settings"
   allSettings: string;           // subbar dropdown "All Settings"
   logout: string;                // user dropdown "Logout"
+  myProfile: string;             // user dropdown "My Profile" (cross-app link to gscMy)
   docs: string;                  // footer "Docs"
   browseApps: string;            // browse-apps "Browse apps"
   viewAll: string;               // browse-apps "View all"
@@ -168,6 +170,20 @@ export type AdminShellProps = {
 
   // Behavior
   onSignOut?: () => void | Promise<void>;
+  /**
+   * Override the path the LogoutButton anchor points at. Defaults to
+   * `/api/auth/signout` — the canonical RP-initiated logout endpoint
+   * (single redirect: kills NextAuth cookie + ends Keycloak SSO + lands
+   * on the app's signed-out page).
+   */
+  signoutPath?: string;
+  /**
+   * URL the "My Profile" item in the user dropdown points at. Defaults
+   * to the canonical gscMy profile page (`https://my.gosec.internal/profile`).
+   * gscMy itself should override this to its own local `/profile` route.
+   * Pass `null` to omit the item entirely.
+   */
+  myProfileUrl?: string | null;
   labels?: Partial<ChromeLabels>;
 
   children: ReactNode;

src/forms/index.ts

@@ -59,7 +59,6 @@ export {
   useValidation,
   useFieldValidation,
   useAddressAutocomplete,
-  loadGoogleMapsScript,
 } from "@limitless/ui";
 
 // Validation — format validators

src/i18n/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @gsc/web-kit/i18n — placeholder for future client-side i18n helpers
+ * (locale switcher component, etc.). The server-side factory lives in
+ * `@gsc/web-kit/i18n/server` so consumer client bundles don't pull in
+ * next/headers and next-intl/server.
+ */
+export {};

src/i18n/server.ts

@@ -0,0 +1,140 @@
+/**
+ * @gsc/web-kit/i18n/server — next-intl request config factory.
+ *
+ * Resolves the active locale from:
+ *   1. `NEXT_LOCALE` cookie (set by an in-app language switcher; beats
+ *      the token claim until the next refresh).
+ *   2. Keycloak access-token `preferred_language` claim, sourced from
+ *      FreeIPA's `preferredLanguage` user attribute via the gosecCloud
+ *      realm's `preferred-language` LDAP mapper + per-client OIDC
+ *      `oidc-usermodel-attribute-mapper`.
+ *   3. `Accept-Language` request header.
+ *   4. `defaultLocale`.
+ *
+ * Mirrors `createAuth()` from `@gsc/web-kit/auth/server`: one factory
+ * call, app supplies the locale list and message loader, kit owns the
+ * resolution chain.
+ *
+ * @example
+ *   // src/i18n/request.ts
+ *   import { createI18nConfig } from "@gsc/web-kit/i18n/server";
+ *   import { auth } from "@/auth";
+ *
+ *   export const locales = ["en", "de", "fr"] as const;
+ *   export const defaultLocale = "en" as const;
+ *
+ *   export default createI18nConfig({
+ *     locales,
+ *     defaultLocale,
+ *     getAccessToken: async () =>
+ *       (await auth())?.user?.accessToken as string | undefined,
+ *     loadMessages: (locale) =>
+ *       import(`../../public/locales/${locale}/common.json`).then((m) => m.default),
+ *   });
+ */
+import { getRequestConfig } from "next-intl/server";
+import { cookies, headers } from "next/headers";
+
+export interface CreateI18nOptions<L extends string> {
+  /** Supported locale codes. First entry is conventional UI fallback order. */
+  locales: readonly L[];
+  /** Locale used when nothing in the resolution chain matches. */
+  defaultLocale: L;
+  /**
+   * Return the current user's Keycloak access token, or undefined if no
+   * session. Typically `async () => (await auth())?.user?.accessToken`.
+   * The kit doesn't import the app's auth module — pass it explicitly so
+   * the kit stays decoupled from how the app wires NextAuth.
+   */
+  getAccessToken?: () => Promise<string | undefined>;
+  /** Load the message bundle for a resolved locale. */
+  loadMessages: (locale: L) => Promise<Record<string, unknown>>;
+  /**
+   * JWT claim name carrying the user's preferred language. Default
+   * `preferred_language` — matches the gosecCloud per-client OIDC mapper
+   * named `preferredLanguage` (config `claim.name=preferred_language`).
+   */
+  claimName?: string;
+  /** Cookie name carrying a recent in-app language switch. Default `NEXT_LOCALE`. */
+  cookieName?: string;
+}
+
+function decodeAccessTokenClaim(
+  accessToken: string,
+  claimName: string,
+): string | undefined {
+  // Plain base64url-decode of the JWT payload. We don't verify here:
+  // NextAuth already verified the ID token via OIDC, the access token
+  // came back over the same TLS exchange, and the only use is a local
+  // locale preference. Same approach as `rolesFromAccessToken` in
+  // auth/server.ts.
+  const parts = accessToken.split(".");
+  if (parts.length < 2) return undefined;
+  try {
+    const payload = parts[1];
+    const padded = payload + "=".repeat((4 - (payload.length % 4)) % 4);
+    const decoded = Buffer.from(
+      padded.replace(/-/g, "+").replace(/_/g, "/"),
+      "base64",
+    ).toString("utf-8");
+    const claims = JSON.parse(decoded) as Record<string, unknown>;
+    const value = claims[claimName];
+    return typeof value === "string" ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function createI18nConfig<L extends string>(opts: CreateI18nOptions<L>) {
+  const claimName = opts.claimName ?? "preferred_language";
+  const cookieName = opts.cookieName ?? "NEXT_LOCALE";
+  const localeSet = new Set<string>(opts.locales);
+  const isLocale = (v: unknown): v is L =>
+    typeof v === "string" && localeSet.has(v);
+
+  return getRequestConfig(async () => {
+    const cookieStore = await cookies();
+    const cookieLocale = cookieStore.get(cookieName)?.value;
+
+    let locale: L | undefined = isLocale(cookieLocale) ? cookieLocale : undefined;
+
+    if (!locale && opts.getAccessToken) {
+      try {
+        const token = await opts.getAccessToken();
+        if (token) {
+          const claim = decodeAccessTokenClaim(token, claimName);
+          if (isLocale(claim)) locale = claim;
+        }
+      } catch {
+        // Session read failed (e.g. missing cookie outside a request
+        // scope). Fall through to Accept-Language.
+      }
+    }
+
+    if (!locale) {
+      const headersList = await headers();
+      const acceptLanguage = headersList.get("accept-language");
+      if (acceptLanguage) {
+        const candidate = acceptLanguage.split(",")[0]?.split("-")[0];
+        if (isLocale(candidate)) locale = candidate;
+      }
+    }
+
+    if (!locale) locale = opts.defaultLocale;
+
+    return {
+      locale,
+      messages: await opts.loadMessages(locale),
+      onError(error) {
+        if (error.code === "MISSING_MESSAGE") {
+          console.warn(error.message);
+        } else {
+          console.error(error);
+        }
+      },
+      getMessageFallback({ key }) {
+        return key;
+      },
+    };
+  });
+}