nexus-shared 1.1.18 → 1.1.19

package/src/services/message-services.tsx

@@ -0,0 +1,383 @@
+import { DEFAULT_ANIMATION_DURATION, DEFAULT_ICON_ELEMENT_NAME, EAnimationClasses, EBackgrounds, ECallbackTypes, EIcons, EIconTypes, EMessageBoxButtons, EMessageIcons, EMessageResult, EMessageTypes, EOpacity, ESizes, PopupMessageCallback, UN } from "nexus-shared";
+import { CreateIconBox, IsBrowser, PxToRem, RemoveElement } from "nexus-shared/client";
+
+const MESSAGE_IDENTITY = "nexus-message";
+const MESSAGE_GAP_REM = 0.8;
+const MESSAGE_TOP_REM = 1;
+const PROGRESS_BAR_HEIGHT_REM = 0.2;
+
+/** Newest first — index 0 is the top message. */
+const activeMessages: HTMLElement[] = [];
+const messageProgressCleanups = new WeakMap<HTMLElement, () => void>();
+let reflowScheduled = false;
+
+const stopMessageProgress = (messageElement: HTMLElement) => {
+  messageProgressCleanups.get(messageElement)?.();
+  messageProgressCleanups.delete(messageElement);
+};
+
+const startMessageProgress = (messageElement: HTMLElement, progressFillElement: HTMLElement, durationMilliseconds: number, onComplete: () => void) => {
+  let elapsedMilliseconds = 0;
+  let lastFrameTimestamp: number | null = null;
+  let animationFrameId = 0;
+
+  const cancelAnimation = () => {
+    if (animationFrameId) cancelAnimationFrame(animationFrameId);
+    animationFrameId = 0;
+  };
+
+  const finishProgress = () => {
+    cancelAnimation();
+    messageProgressCleanups.delete(messageElement);
+    onComplete();
+  };
+
+  const updateProgress = (frameTimestamp: number) => {
+    animationFrameId = 0;
+    if (lastFrameTimestamp !== null) {
+      elapsedMilliseconds += frameTimestamp - lastFrameTimestamp;
+      progressFillElement.style.width = `${Math.min((elapsedMilliseconds / durationMilliseconds) * 100, 100)}%`;
+      if (elapsedMilliseconds >= durationMilliseconds) return finishProgress();
+    }
+    lastFrameTimestamp = frameTimestamp;
+    animationFrameId = requestAnimationFrame(updateProgress);
+  };
+
+  const onMouseEnter = () => {
+    lastFrameTimestamp = null;
+    cancelAnimation();
+  };
+  const onMouseLeave = () => {
+    if (!animationFrameId) animationFrameId = requestAnimationFrame(updateProgress);
+  };
+
+  messageElement.addEventListener("mouseenter", onMouseEnter);
+  messageElement.addEventListener("mouseleave", onMouseLeave);
+  messageProgressCleanups.set(messageElement, () => {
+    cancelAnimation();
+    messageElement.removeEventListener("mouseenter", onMouseEnter);
+    messageElement.removeEventListener("mouseleave", onMouseLeave);
+  });
+  animationFrameId = requestAnimationFrame(updateProgress);
+};
+
+const scheduleReflow = () => {
+  if (reflowScheduled) return;
+  reflowScheduled = true;
+  requestAnimationFrame(() => {
+    reflowScheduled = false;
+    let offset = MESSAGE_TOP_REM;
+    for (const el of activeMessages) {
+      el.style.top = `${offset}rem`;
+      offset += PxToRem(el.offsetHeight) + MESSAGE_GAP_REM;
+    }
+  });
+};
+
+const dismissMessage = (el: HTMLElement, callback?: PopupMessageCallback) => {
+  const index = activeMessages.indexOf(el);
+  if (index === -1) return;
+
+  stopMessageProgress(el);
+  activeMessages.splice(index, 1);
+  el.style.right = "-100%";
+  el.style.top = "100%";
+  RemoveElement(el, DEFAULT_ANIMATION_DURATION, EAnimationClasses.FADE_OUT);
+  scheduleReflow();
+  callback?.(ECallbackTypes.Destroy);
+};
+
+const _showMessage = (title: string, message: string, messageType: EMessageTypes, delay?: number | UN, duration?: number | UN, icon?: EMessageIcons | UN, callback?: PopupMessageCallback) => {
+  if (!IsBrowser()) return;
+
+  delay = delay ?? 0;
+  duration = duration ?? 3000;
+
+  const createAndShow = () => {
+    /** Root message element */
+    const messageRootElement = document.createElement("div");
+    const messageBodyElement = document.createElement("div");
+    const messageHandleElement = document.createElement("div");
+    const messageContentElement = document.createElement("div");
+    const messageIconElement = document.createElement("div");
+    const progressTrackElement = document.createElement("div");
+    const progressFillElement = document.createElement("div");
+
+    document.body.appendChild(messageRootElement);
+    messageRootElement.appendChild(messageBodyElement);
+    messageBodyElement.appendChild(messageHandleElement);
+    messageBodyElement.appendChild(messageIconElement);
+    messageBodyElement.appendChild(messageContentElement);
+    messageRootElement.appendChild(progressTrackElement);
+    progressTrackElement.appendChild(progressFillElement);
+
+    messageRootElement.className = `${MESSAGE_IDENTITY} pf bs3 r bg1 anim df ddc oh`;
+    messageBodyElement.className = "df ac w100";
+    messageHandleElement.className = messageType;
+    messageIconElement.className = `ib ml4 sm rr ${messageType}`;
+    messageContentElement.className = `p4 pr2 fg`;
+    progressTrackElement.className = "w100";
+    progressFillElement.className = messageType;
+
+    messageRootElement.style.right = "-100%";
+    messageRootElement.style.transitionDuration = `${DEFAULT_ANIMATION_DURATION * 1.5}ms`;
+
+    messageHandleElement.style.width = "0.3rem";
+    messageHandleElement.style.alignSelf = "stretch";
+    messageHandleElement.style.flexShrink = "0";
+
+    progressTrackElement.style.height = `${PROGRESS_BAR_HEIGHT_REM}rem`;
+    progressTrackElement.style.flexShrink = "0";
+    progressFillElement.style.height = "100%";
+    progressFillElement.style.width = "0%";
+
+    messageIconElement.innerHTML = `<${DEFAULT_ICON_ELEMENT_NAME} class="icon" name="${icon}" />`;
+
+    const _TM = setTimeout(() => {
+      clearTimeout(_TM);
+      const WINDOW_WIDTH = window.innerWidth;
+      if (WINDOW_WIDTH > 1000) {
+        messageRootElement.style.right = "1rem";
+        messageRootElement.style.maxWidth = "35rem";
+        messageRootElement.style.minWidth = "16rem";
+      } else {
+        messageRootElement.style.maxWidth = "calc(100vw - 1rem)";
+        messageRootElement.style.minWidth = "15rem";
+        messageRootElement.style.right = "0.5rem";
+      }
+    }, 0);
+
+    const titleElement = document.createElement("p");
+    const messageElement = document.createElement("p");
+    titleElement.className = "mb1 fw600 w100 df ac";
+    messageElement.className = "o08 fs-09 pr3";
+    titleElement.innerHTML = `<p class="w100 fg">${title}</p>`;
+    messageElement.innerHTML = message;
+    messageContentElement.appendChild(titleElement);
+    messageContentElement.appendChild(messageElement);
+
+    const dismiss = () => dismissMessage(messageRootElement, callback);
+    CreateIconBox(EIcons.CLOSE, titleElement, null, null, EIconTypes.FILLED, EBackgrounds.Background1, ESizes.VeryTiny, ESizes.Tiny, null, null, null, null, EOpacity.O05, "Clear Message", null, null, null, dismiss);
+
+    activeMessages.unshift(messageRootElement);
+    scheduleReflow();
+    requestAnimationFrame(scheduleReflow);
+    callback?.(ECallbackTypes.Initialize);
+
+    if (duration > 0) startMessageProgress(messageRootElement, progressFillElement, duration, dismiss);
+  };
+
+  if (typeof delay === "number" && delay > 0) {
+    const _TM = window.setTimeout(() => {
+      clearTimeout(_TM);
+      createAndShow();
+    }, delay);
+  } else createAndShow();
+};
+
+export const SuccessMessage = (title: string, message: string, delay?: number | UN, duration?: number | UN, callback?: PopupMessageCallback, icon?: EMessageIcons | UN) => {
+  return _showMessage(title, message, EMessageTypes.Success, delay, duration, icon ?? EMessageIcons.Success, callback);
+};
+export const ErrorMessage = (title: string, message: string, delay?: number | UN, duration?: number | UN, callback?: PopupMessageCallback, icon?: EMessageIcons | UN) => {
+  return _showMessage(title, message, EMessageTypes.Error, delay, duration, icon ?? EMessageIcons.Error, callback);
+};
+export const WarningMessage = (title: string, message: string, delay?: number | UN, duration?: number | UN, callback?: PopupMessageCallback, icon?: EMessageIcons | UN) => {
+  return _showMessage(title, message, EMessageTypes.Warning, delay, duration, icon ?? EMessageIcons.Warning, callback);
+};
+export const InformationMessage = (title: string, message: string, delay?: number | UN, duration?: number | UN, callback?: PopupMessageCallback, icon?: EMessageIcons | UN) => {
+  return _showMessage(title, message, EMessageTypes.Information, delay, duration, icon ?? EMessageIcons.Information, callback);
+};
+export const QuestionMessage = (title: string, message: string, delay?: number | UN, duration?: number | UN, callback?: PopupMessageCallback, icon?: EMessageIcons | UN) => {
+  return _showMessage(title, message, EMessageTypes.Information, delay, duration, icon ?? EMessageIcons.Question, callback);
+};
+
+type MessageBoxButton = {
+  result: EMessageResult;
+  label: string;
+  themeBackgroundClass?: EBackgrounds | string;
+};
+
+const normalizeMessageResult = (value: string): EMessageResult => {
+  const v = (value ?? "").trim().toLowerCase();
+  if (v === "ok") return EMessageResult.OK;
+  if (v === "yes") return EMessageResult.Yes;
+  if (v === "no") return EMessageResult.No;
+  if (v === "cancel") return EMessageResult.Cancel;
+  return EMessageResult.Undefined;
+};
+
+const getMessageBoxButtons = (messageButtons: EMessageBoxButtons, themeBackgroundClass: EMessageTypes, overrideYesButtonText?: string | null): MessageBoxButton[] => {
+  const parts = (messageButtons ?? EMessageBoxButtons.OK).split("_").filter(Boolean);
+  const results = parts.map(normalizeMessageResult).filter((r) => r !== EMessageResult.Undefined);
+  const resolved = results.length ? results : [EMessageResult.OK];
+
+  return resolved.map((result) => {
+    if (result === EMessageResult.Yes) return { result, label: overrideYesButtonText ?? "Yes", themeBackgroundClass };
+    if (result === EMessageResult.OK) return { result, label: "OK", themeBackgroundClass: themeBackgroundClass };
+    if (result === EMessageResult.No) return { result, label: "No", themeBackgroundClass: EBackgrounds.AlwaysDarkBackgroundColor };
+    if (result === EMessageResult.Cancel) return { result, label: "Cancel", themeBackgroundClass: EBackgrounds.AlwaysDarkBackgroundColor };
+    return { result, label: String(result) };
+  });
+};
+
+const getCloseResult = (buttons: MessageBoxButton[]): EMessageResult => {
+  if (buttons.some((b) => b.result === EMessageResult.Cancel)) return EMessageResult.Cancel;
+  if (buttons.some((b) => b.result === EMessageResult.No)) return EMessageResult.No;
+  if (buttons.some((b) => b.result === EMessageResult.OK)) return EMessageResult.OK;
+  return EMessageResult.Undefined;
+};
+
+/**
+ * Windows-like modal message box (DOM-based).
+ * - Keyboard: Tab / Shift+Tab / ArrowLeft / ArrowRight to move focus
+ * - Enter: activates focused button
+ * - Escape: closes with Cancel/No/OK (in that order if present)
+ */
+export const ShowDialogMessageBox = async (messageButtons: EMessageBoxButtons, title: string, message: string, iconName: EMessageIcons, themeBackgroundClass?: EMessageTypes, overrideYesButtonText?: string | null, confirmMessage?: string | null, allowOverlayClick?: boolean): Promise<EMessageResult | null> => {
+  if (!IsBrowser()) return null;
+
+  return new Promise((resolve) => {
+    themeBackgroundClass = themeBackgroundClass ?? EMessageTypes.Information;
+    const bodyElement = document.body as HTMLBodyElement;
+    const overlayElement = document.createElement("div") as HTMLDivElement;
+    const dialogElement = document.createElement("div") as HTMLDivElement;
+
+    const iconBoxElement = document.createElement("div") as HTMLDivElement;
+    const headerElement = document.createElement("div") as HTMLDivElement;
+    const headerTextElement = document.createElement("div") as HTMLDivElement;
+    const titleElement = document.createElement("h4") as HTMLHeadingElement;
+    const messageElement = document.createElement("p") as HTMLParagraphElement;
+    const confirmElement = document.createElement("p") as HTMLParagraphElement;
+    const buttonRowElement = document.createElement("div") as HTMLDivElement;
+
+    const buttons = getMessageBoxButtons(messageButtons, themeBackgroundClass, overrideYesButtonText);
+    const actionButtons: HTMLButtonElement[] = [];
+    let currentFocusIndex = 0;
+    let isClosed = false;
+
+    overlayElement.className = `pf df ac jc ${EBackgrounds.PopupBackgroundColor} ${EAnimationClasses.FADE_IN}`;
+    overlayElement.style.zIndex = "100000";
+    overlayElement.style.inset = "0";
+
+    dialogElement.className = `bg1 r bs3 anim df ddc`;
+    dialogElement.style.maxWidth = "36rem";
+    dialogElement.style.width = "calc(100vw - 2rem)";
+    dialogElement.style.boxSizing = "border-box";
+
+    headerElement.className = "df w100";
+    headerElement.style.gap = "1rem";
+    headerElement.style.padding = "1.25rem";
+
+    iconBoxElement.className = `df ac jc rr bb ${themeBackgroundClass}`;
+    iconBoxElement.style.minWidth = "4rem";
+    iconBoxElement.style.maxWidth = "4rem";
+    iconBoxElement.style.minHeight = "4rem";
+    iconBoxElement.style.maxHeight = "4rem";
+
+    const iconElement = document.createElement(DEFAULT_ICON_ELEMENT_NAME) as HTMLElement & { name?: string };
+    iconElement.name = `${iconName}${EIconTypes.OUTLINED}`;
+    iconElement.className = `icon ${ESizes.Large} o08`;
+    iconElement.style.color = "white";
+    iconBoxElement.appendChild(iconElement);
+
+    headerTextElement.className = "fg";
+
+    titleElement.className = "fw600";
+    titleElement.style.margin = "0";
+    titleElement.innerText = title ?? "";
+
+    messageElement.className = "o08";
+    messageElement.style.margin = "0.5rem 0 0 0";
+    messageElement.innerHTML = message ?? "";
+
+    confirmElement.className = "o08";
+    confirmElement.style.margin = "0.75rem 0 0 0";
+    confirmElement.innerHTML = confirmMessage ?? "";
+    if (!confirmMessage) confirmElement.style.display = "none";
+
+    buttonRowElement.className = "df w100";
+    buttonRowElement.style.gap = "0.75rem";
+    buttonRowElement.style.justifyContent = "flex-end";
+    buttonRowElement.style.padding = "0 1.25rem 1.25rem 1.25rem";
+
+    const setFocus = (index: number) => {
+      currentFocusIndex = Math.min(Math.max(index, 0), actionButtons.length - 1);
+      actionButtons[currentFocusIndex]?.focus();
+    };
+
+    const closeDialog = (result: EMessageResult) => {
+      if (isClosed) return;
+      isClosed = true;
+
+      document.removeEventListener("keydown", onKeyDown);
+      overlayElement.removeEventListener("click", onOverlayClick);
+
+      overlayElement.classList.remove(EAnimationClasses.FADE_IN);
+      overlayElement.classList.add(EAnimationClasses.FADE_OUT);
+      dialogElement.classList.add(EAnimationClasses.PULSE_OUT);
+
+      RemoveElement(overlayElement, DEFAULT_ANIMATION_DURATION, EAnimationClasses.FADE_OUT).finally(() => resolve(result));
+    };
+
+    const onOverlayClick = (event: MouseEvent) => {
+      if (event.target === overlayElement) closeDialog(getCloseResult(buttons));
+    };
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      const key = event.key;
+      const isShiftTab = key === "Tab" && event.shiftKey;
+      const isTab = key === "Tab" && !event.shiftKey;
+
+      if (key === "ArrowLeft" || isShiftTab) {
+        event.preventDefault();
+        setFocus((currentFocusIndex - 1 + actionButtons.length) % actionButtons.length);
+      } else if (key === "ArrowRight" || isTab) {
+        event.preventDefault();
+        setFocus((currentFocusIndex + 1) % actionButtons.length);
+      } else if (key === "Enter") {
+        event.preventDefault();
+        const result = buttons[currentFocusIndex]?.result ?? EMessageResult.Undefined;
+        closeDialog(result);
+      } else if (key === "Escape") {
+        event.preventDefault();
+        closeDialog(getCloseResult(buttons));
+      }
+    };
+
+    const createButton = (button: MessageBoxButton) => {
+      const buttonElement = document.createElement("button") as HTMLButtonElement;
+      buttonElement.type = "button";
+      buttonElement.className = `sn r h p2 pr4 pl4 ${button.themeBackgroundClass}`;
+      buttonElement.style.minWidth = "5.5rem";
+      buttonElement.innerText = button.label;
+
+      const onClick = () => closeDialog(button.result);
+      buttonElement.addEventListener("click", onClick, { once: true });
+      return buttonElement;
+    };
+
+    for (const button of buttons) {
+      const buttonElement = createButton(button);
+      buttonRowElement.appendChild(buttonElement);
+      actionButtons.push(buttonElement);
+    }
+
+    headerTextElement.appendChild(titleElement);
+    headerTextElement.appendChild(messageElement);
+    headerTextElement.appendChild(confirmElement);
+
+    headerElement.appendChild(iconBoxElement);
+    headerElement.appendChild(headerTextElement);
+
+    dialogElement.appendChild(headerElement);
+    dialogElement.appendChild(buttonRowElement);
+
+    overlayElement.appendChild(dialogElement);
+    bodyElement.insertBefore(overlayElement, bodyElement.firstChild);
+
+    if (allowOverlayClick === false) overlayElement.addEventListener("click", onOverlayClick);
+    document.addEventListener("keydown", onKeyDown);
+
+    setTimeout(() => setFocus(0), 0);
+  });
+};

package/src/sso-config/auth-token-validation.ts

@@ -0,0 +1,20 @@
+import { IUserValidationResponse } from "../interfaces/user-interfaces";
+import { HttpGet } from "../services/http-services";
+import { SSO_CONFIG } from "./sso-config";
+
+/**
+ * Verifies the access token by calling the backend Authentication/Verify endpoint.
+ * Returns true when the backend responds with HTTP 200 (token accepted), false for any
+ * other status or network failure. No JWT secrets or JWKS keys are needed in Next.js.
+ */
+export async function VerifyAccessToken(token: string): Promise<boolean> {
+  if (!token?.trim()) return false;
+  try {
+    const response = await HttpGet(SSO_CONFIG.BACKEND_ENDPOINTS.VERIFY, token);
+    if (!response.isSuccess) return false;
+    const validationResponse = response.result as IUserValidationResponse;
+    return validationResponse.isValidUser;
+  } catch {
+    return false;
+  }
+}

package/src/sso-config/callback-route.tsx

@@ -0,0 +1,34 @@
+import { NextRequest, NextResponse } from "next/server";
+import { URLS } from "../nexus.environments";
+import { SetAuthCookies } from "./cookie-helpers";
+import { DecodeOAuthCallbackState } from "./oauth-callback-state";
+import { SanitizeReturnPath } from "./redirect-context-helpers";
+import { BuildAuthenticationSignInUrl, SSO_CONFIG } from "./sso-config";
+import { ExchangeAuthorizationCode } from "./sso-backend-flow";
+
+export async function CallbackRoute(req: NextRequest) {
+  const code = req.nextUrl.searchParams.get("code");
+  const state = req.nextUrl.searchParams.get("state");
+  const callbackState = DecodeOAuthCallbackState(state);
+  const failUrl = new URL(BuildAuthenticationSignInUrl(callbackState?.returnPath));
+
+  if (!code) return NextResponse.redirect(failUrl);
+
+  if (!callbackState?.codeVerifier) return NextResponse.redirect(failUrl);
+
+  try {
+    const tokenData = await ExchangeAuthorizationCode({
+      code,
+      redirectUri: SSO_CONFIG.FRONTEND_ENDPOINTS.CALLBACK,
+      codeVerifier: callbackState.codeVerifier,
+    });
+    if (!tokenData) return NextResponse.redirect(failUrl);
+
+    const redirectTarget = new URL(SanitizeReturnPath(tokenData.returnPath ?? callbackState.returnPath), URLS.CURRENT!);
+    const response = NextResponse.redirect(redirectTarget);
+    SetAuthCookies(response, tokenData);
+    return response;
+  } catch {
+    return NextResponse.redirect(new URL(BuildAuthenticationSignInUrl(callbackState?.returnPath)));
+  }
+}

package/src/sso-config/cookie-encryption.ts

@@ -0,0 +1,51 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "crypto";
+
+const ALGORITHM = "aes-256-gcm";
+const IV_BYTES = 12; // 96-bit IV recommended for GCM
+
+/**
+ * Derives a 32-byte AES key from SSO_COOKIE_SECRET using SHA-256.
+ * The secret itself is never sent to the browser.
+ */
+function deriveKey(): Buffer {
+  const raw = process.env.SSO_COOKIE_SECRET?.trim();
+  const secret = raw && !raw.startsWith("$") ? raw : process.env.NODE_ENV === "development" ? "NexusDevAuthSecretKey2026MustBe32CharsLong!" : null;
+  if (!secret) throw new Error("SSO_COOKIE_SECRET must be configured for cookie encryption.");
+  return createHash("sha256").update(secret).digest();
+}
+
+/**
+ * Encrypts a cookie value with AES-256-GCM.
+ * Output format: `<iv>.<authTag>.<ciphertext>` (all base64url).
+ * The browser stores only this opaque string — the raw token is never exposed.
+ */
+export function EncryptCookieValue(value: string): string {
+  const key = deriveKey();
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+  const encrypted = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+  return `${iv.toString("base64url")}.${authTag.toString("base64url")}.${encrypted.toString("base64url")}`;
+}
+
+/**
+ * Decrypts a cookie value produced by EncryptCookieValue.
+ * Returns null if the value is missing, malformed, or the auth tag fails (tampered).
+ */
+export function DecryptCookieValue(value: string): string | null {
+  if (!value) return null;
+  try {
+    const parts = value.split(".");
+    if (parts.length !== 3) return null;
+    const key = deriveKey();
+    const iv = Buffer.from(parts[0], "base64url");
+    const authTag = Buffer.from(parts[1], "base64url");
+    const encrypted = Buffer.from(parts[2], "base64url");
+    const decipher = createDecipheriv(ALGORITHM, key, iv);
+    decipher.setAuthTag(authTag);
+    const decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()]);
+    return decrypted.toString("utf8");
+  } catch {
+    return null;
+  }
+}

package/src/sso-config/cookie-helpers.tsx

@@ -0,0 +1,77 @@
+import { cookies } from "next/headers";
+import { NextRequest, NextResponse } from "next/server";
+import { VerifyAccessToken } from "./auth-token-validation";
+import { DecryptCookieValue, EncryptCookieValue } from "./cookie-encryption";
+import { GetAuthCookieOptions } from "./redirect-context-helpers";
+import { CookieInfo, SSOAuthResponse } from "./sso-interfaces";
+
+export const AUTH_COOKIES = {
+  ssoSession: "sso_session",
+  accessToken: "access_token",
+  refreshToken: "refresh_token",
+  redirectContext: "sso_redirect_ctx",
+} as const;
+
+export function SetAuthCookies(response: NextResponse, tokens: SSOAuthResponse) {
+  response.cookies.set(AUTH_COOKIES.accessToken, EncryptCookieValue(tokens.accessToken), GetAuthCookieOptions(tokens.expiresTokenIn));
+  response.cookies.set(AUTH_COOKIES.refreshToken, EncryptCookieValue(tokens.refreshToken), GetAuthCookieOptions(tokens.expiresRefreshTokenIn));
+}
+
+export function SetSsoSessionCookie(response: NextResponse, ssoSession: string, maxAge: number | string) {
+  response.cookies.set(AUTH_COOKIES.ssoSession, EncryptCookieValue(ssoSession), GetAuthCookieOptions(maxAge ?? 28800));
+}
+
+export function ClearAuthCookies(response: NextResponse) {
+  response.cookies.set(AUTH_COOKIES.accessToken, "", GetAuthCookieOptions(0));
+  response.cookies.set(AUTH_COOKIES.refreshToken, "", GetAuthCookieOptions(0));
+}
+
+export function ClearAllAuthCookies(response: NextResponse) {
+  response.cookies.set(AUTH_COOKIES.ssoSession, "", GetAuthCookieOptions(0));
+  ClearAuthCookies(response);
+}
+
+/**
+ * Reads and decrypts a single auth cookie from an incoming NextRequest.
+ * Returns null when the cookie is absent or the encrypted value is tampered / unreadable.
+ */
+export function GetDecryptedRequestCookie(req: NextRequest, name: string): string | null {
+  const raw = req.cookies.get(name)?.value;
+  if (!raw) return null;
+  return DecryptCookieValue(raw);
+}
+
+export async function GetCookieInfo(): Promise<CookieInfo | null> {
+  const cookieStore = await cookies();
+
+  const rawSsoSession = cookieStore.get(AUTH_COOKIES.ssoSession)?.value;
+  if (!rawSsoSession) return null;
+  const ssoSession = DecryptCookieValue(rawSsoSession);
+  if (!ssoSession) return null;
+
+  const rawAccessToken = cookieStore.get(AUTH_COOKIES.accessToken)?.value;
+  const rawRefreshToken = cookieStore.get(AUTH_COOKIES.refreshToken)?.value;
+
+  return {
+    ssoSession,
+    accessToken: rawAccessToken ? (DecryptCookieValue(rawAccessToken) ?? undefined) : undefined,
+    refreshToken: rawRefreshToken ? (DecryptCookieValue(rawRefreshToken) ?? undefined) : undefined,
+  };
+}
+
+/** True when this client app has a valid access token (use on all non-auth client sites). */
+export async function HasAccessToken(): Promise<boolean> {
+  const cookieStore = await cookies();
+  const raw = cookieStore.get(AUTH_COOKIES.accessToken)?.value;
+  if (!raw) return false;
+  const token = DecryptCookieValue(raw);
+  if (!token) return false;
+  return VerifyAccessToken(token);
+}
+
+/** True on the central auth app when user has SSO session or a valid local access token. */
+export async function HasAuthSession(): Promise<boolean> {
+  const cookieStore = await cookies();
+  const rawSsoSession = cookieStore.get(AUTH_COOKIES.ssoSession)?.value;
+  return !!(rawSsoSession && DecryptCookieValue(rawSsoSession));
+}

package/src/sso-config/forgot-password-route.tsx

@@ -0,0 +1,36 @@
+import { NextRequest, NextResponse } from "next/server";
+import { HttpPost } from "../services/http-services";
+import { SSO_CONFIG } from "./sso-config";
+
+export async function ForgotPasswordPostRoute(req: NextRequest) {
+  const body = (await req.json()) as { usernameOrEmail?: string };
+  if (!body.usernameOrEmail?.trim()) {
+    return NextResponse.json({ error: "Username or email is required." }, { status: 400 });
+  }
+
+  const response = await HttpPost(SSO_CONFIG.BACKEND_ENDPOINTS.FORGOT_PASSWORD, {
+    usernameOrEmail: body.usernameOrEmail.trim(),
+  });
+
+  if (!response.isSuccess) {
+    return NextResponse.json(response, { status: response.code ?? 400 });
+  }
+
+  return NextResponse.json(response);
+}
+
+export async function ResetPasswordPostRoute(req: NextRequest) {
+  const body = (await req.json()) as {
+    resetSessionToken?: string;
+    verificationCode?: string;
+    newPassword?: string;
+    confirmPassword?: string;
+  };
+
+  const response = await HttpPost(SSO_CONFIG.BACKEND_ENDPOINTS.RESET_PASSWORD, body);
+  if (!response.isSuccess) {
+    return NextResponse.json(response, { status: response.code ?? 400 });
+  }
+
+  return NextResponse.json(response);
+}

package/src/sso-config/oauth-callback-state.ts

@@ -0,0 +1,58 @@
+import { createHmac, timingSafeEqual } from "crypto";
+import { SanitizeReturnPath } from "./redirect-context-helpers";
+
+type EncodedCallbackState = {
+  n: string;
+  p: string;
+  v: string;
+  t: number;
+};
+
+function getCookieSecret(): string {
+  const ssoSecret = process.env.SSO_COOKIE_SECRET?.trim();
+  const secret = ssoSecret && !ssoSecret.startsWith("$") ? ssoSecret : undefined;
+  if (secret) return secret;
+  if (process.env.NODE_ENV === "development") return "NexusDevAuthSecretKey2026MustBe32CharsLong!";
+  throw new Error("SSO_COOKIE_SECRET must be configured.");
+}
+
+function signPayload(data: string): string {
+  return createHmac("sha256", getCookieSecret()).update(data).digest("base64url");
+}
+
+/** Signed OAuth callback state (nonce + return path + PKCE verifier). */
+export function EncodeOAuthCallbackState(nonce: string, returnPath: string, codeVerifier: string): string {
+  const payload: EncodedCallbackState = {
+    n: nonce,
+    p: SanitizeReturnPath(returnPath),
+    v: codeVerifier,
+    t: Date.now(),
+  };
+  const data = Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+  return `${data}.${signPayload(data)}`;
+}
+
+export function DecodeOAuthCallbackState(value?: string | null): { nonce: string; returnPath: string; codeVerifier: string } | null {
+  if (!value) return null;
+
+  try {
+    const [data, signature] = value.split(".");
+    if (!data || !signature) return null;
+
+    const expected = signPayload(data);
+    if (signature.length !== expected.length || !timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
+      return null;
+    }
+
+    const payload = JSON.parse(Buffer.from(data, "base64url").toString("utf8")) as EncodedCallbackState;
+    if (!payload?.n || !payload?.v) return null;
+
+    return {
+      nonce: payload.n,
+      returnPath: SanitizeReturnPath(payload.p),
+      codeVerifier: payload.v,
+    };
+  } catch {
+    return null;
+  }
+}

package/src/sso-config/pkce-helpers.ts

@@ -0,0 +1,16 @@
+import { randomBytes, createHash } from "crypto";
+
+export const PKCE_METHOD_S256 = "S256";
+
+export type PkcePair = {
+  verifier: string;
+  challenge: string;
+  method: typeof PKCE_METHOD_S256;
+};
+
+/** Creates an OAuth PKCE pair (RFC 7636) using S256. */
+export function CreatePkcePair(): PkcePair {
+  const verifier = randomBytes(32).toString("base64url");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  return { verifier, challenge, method: PKCE_METHOD_S256 };
+}