nexus-shared 1.1.18 → 1.1.19

package/src/sso-config/provider-complete-route.tsx

@@ -0,0 +1,15 @@
+import { NextRequest, NextResponse } from "next/server";
+import { SetSsoSessionCookie } from "./cookie-helpers";
+import { SSO_CONFIG } from "./sso-config";
+
+/** GET — complete provider OAuth by persisting the backend SSO session cookie. */
+export async function ProviderCompleteRoute(req: NextRequest) {
+  const signInUrl = new URL("/auth/sign-in", req.url);
+  const ssoSession = req.nextUrl.searchParams.get("ssoSession");
+
+  if (!ssoSession) return NextResponse.redirect(signInUrl);
+
+  const response = NextResponse.redirect(new URL(SSO_CONFIG.FRONTEND_ENDPOINTS.SSO_COMPLETE, req.url));
+  SetSsoSessionCookie(response, ssoSession, SSO_CONFIG.BACKEND_CONFIG.SSO_SESSION_MAX_AGE);
+  return response;
+}

package/src/sso-config/redirect-context-actions.tsx

@@ -0,0 +1,46 @@
+"use server";
+
+import { cookies } from "next/headers";
+import { AUTH_COOKIES } from "./cookie-helpers";
+import { CreatePkcePair } from "./pkce-helpers";
+import { CreateOAuthNonce, DecodeRedirectContext, EncodeRedirectContext, GetRedirectContextCookieOptions, IsAllowedRedirectUri, SanitizeReturnPath } from "./redirect-context-helpers";
+import { IRedirectContext } from "./sso-interfaces";
+
+function ReadRedirectContextFromStore(cookieStore: Awaited<ReturnType<typeof cookies>>): IRedirectContext | null {
+  return DecodeRedirectContext(cookieStore.get(AUTH_COOKIES.redirectContext)?.value);
+}
+
+function WriteRedirectContextToStore(cookieStore: Awaited<ReturnType<typeof cookies>>, context: IRedirectContext) {
+  cookieStore.set(AUTH_COOKIES.redirectContext, EncodeRedirectContext(context), GetRedirectContextCookieOptions());
+}
+
+/** Server Action — persists redirect_uri/state into a signed httpOnly cookie. */
+export async function PersistRedirectContext(redirectUri?: string | null, state?: string | null) {
+  const cookieStore = await cookies();
+  const trimmedUri = redirectUri?.trim();
+
+  if (trimmedUri && IsAllowedRedirectUri(trimmedUri)) {
+    const existing = ReadRedirectContextFromStore(cookieStore);
+    if (existing?.redirectUri === trimmedUri) return;
+
+    const pkce = CreatePkcePair();
+    WriteRedirectContextToStore(cookieStore, {
+      redirectUri: trimmedUri,
+      state: CreateOAuthNonce(),
+      returnPath: SanitizeReturnPath(state),
+      codeChallenge: pkce.challenge,
+      codeChallengeMethod: pkce.method,
+      pkceVerifier: pkce.verifier,
+    });
+    return;
+  }
+
+  const existing = ReadRedirectContextFromStore(cookieStore);
+  if (existing) WriteRedirectContextToStore(cookieStore, existing);
+}
+
+/** Server Action — clears the redirect context cookie after SSO completes. */
+export async function ClearRedirectContext() {
+  const cookieStore = await cookies();
+  cookieStore.delete(AUTH_COOKIES.redirectContext);
+}

package/src/sso-config/redirect-context-helpers.tsx

@@ -0,0 +1,144 @@
+import { createHmac, randomBytes, timingSafeEqual } from "crypto";
+import { cookies } from "next/headers";
+import { NextResponse } from "next/server";
+import { URLS } from "../nexus.environments";
+import { AUTH_COOKIES } from "./cookie-helpers";
+import { CreatePkcePair, PKCE_METHOD_S256 } from "./pkce-helpers";
+import { SSO_CONFIG } from "./sso-config";
+import { IRedirectContext } from "./sso-interfaces";
+
+const CALLBACK_SUFFIX = "/api/auth/callback";
+
+type EncodedRedirectContext = {
+  r: string;
+  s: string;
+  p: string;
+  c: string;
+  m: string;
+  v: string;
+  t: number;
+};
+
+const signPayload = (data: string): string => createHmac("sha256", SSO_CONFIG.COOKIE_CONFIG.COOKIE_SECRET).update(data).digest("base64url");
+
+export function SanitizeReturnPath(value?: string | null): string {
+  if (!value?.trim()) return "/";
+  const path = value.trim();
+  if (!path.startsWith("/") || path.startsWith("//")) return "/";
+  return path;
+}
+
+export function CreateOAuthNonce(): string {
+  return randomBytes(24).toString("base64url");
+}
+
+/** Validates client callback URLs to prevent open redirects. */
+export function IsAllowedRedirectUri(redirectUri: string): boolean {
+  try {
+    const url = new URL(redirectUri);
+    if (!url.pathname.endsWith(CALLBACK_SUFFIX)) return false;
+    if (url.username || url.password) return false;
+    if (url.protocol !== "http:" && url.protocol !== "https:") return false;
+    return URLS.ALLOWED_ORIGINS.includes(url.origin);
+  } catch {
+    return false;
+  }
+}
+
+export function EncodeRedirectContext(context: IRedirectContext): string {
+  const payload: EncodedRedirectContext = {
+    r: context.redirectUri,
+    s: context.state,
+    p: context.returnPath,
+    c: context.codeChallenge,
+    m: context.codeChallengeMethod,
+    v: context.pkceVerifier,
+    t: Date.now(),
+  };
+  const data = Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+  return `${data}.${signPayload(data)}`;
+}
+
+export function DecodeRedirectContext(value?: string | null): IRedirectContext | 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 EncodedRedirectContext;
+    if (!payload?.r || !IsAllowedRedirectUri(payload.r)) return null;
+
+    const ageMs = Date.now() - (payload.t ?? 0);
+    if (ageMs > Number(SSO_CONFIG.BACKEND_CONFIG.REDIRECT_CONTEXT_MAX_AGE) * 1000) return null;
+
+    if (!payload.c || !payload.v) return null;
+
+    return {
+      redirectUri: payload.r,
+      state: payload.s ?? "",
+      returnPath: SanitizeReturnPath(payload.p),
+      codeChallenge: payload.c,
+      codeChallengeMethod: payload.m ?? PKCE_METHOD_S256,
+      pkceVerifier: payload.v,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function createRedirectContext(redirectUri: string, returnPath?: string | null): IRedirectContext {
+  const pkce = CreatePkcePair();
+  return {
+    redirectUri,
+    state: CreateOAuthNonce(),
+    returnPath: SanitizeReturnPath(returnPath),
+    codeChallenge: pkce.challenge,
+    codeChallengeMethod: pkce.method,
+    pkceVerifier: pkce.verifier,
+  };
+}
+
+/** Read-only: resolve redirect context from cookie, or build an in-memory context from URL params (no cookie writes). */
+export async function ReadRedirectContext(redirectUri?: string | null, state?: string | null): Promise<IRedirectContext | null> {
+  const cookieStore = await cookies();
+  const fromCookie = DecodeRedirectContext(cookieStore.get(AUTH_COOKIES.redirectContext)?.value);
+
+  const trimmedUri = redirectUri?.trim();
+  if (trimmedUri && IsAllowedRedirectUri(trimmedUri)) {
+    if (fromCookie?.redirectUri === trimmedUri) {
+      return fromCookie;
+    }
+    return createRedirectContext(trimmedUri, state);
+  }
+
+  return fromCookie;
+}
+
+export function GetAuthCookieOptions(maxAge: number | string) {
+  return {
+    httpOnly: true,
+    path: "/",
+    sameSite: "lax" as const,
+    maxAge: Number(maxAge),
+    secure: process.env.NODE_ENV === "production",
+  };
+}
+
+export function GetRedirectContextCookieOptions() {
+  return GetAuthCookieOptions(SSO_CONFIG.BACKEND_CONFIG.REDIRECT_CONTEXT_MAX_AGE);
+}
+
+export function SetRedirectContextCookie(response: NextResponse, context: IRedirectContext) {
+  if (!IsAllowedRedirectUri(context.redirectUri)) return;
+  response.cookies.set(AUTH_COOKIES.redirectContext, EncodeRedirectContext(context), GetRedirectContextCookieOptions());
+}
+
+export function ClearRedirectContextCookie(response: NextResponse) {
+  response.cookies.set(AUTH_COOKIES.redirectContext, "", { ...GetRedirectContextCookieOptions(), maxAge: 0 });
+}

package/src/sso-config/redirect-context-persist.tsx

@@ -0,0 +1,18 @@
+"use client";
+
+import { useSearchParams } from "next/navigation";
+import { useEffect } from "react";
+import { PersistRedirectContext } from "./redirect-context-actions";
+
+/** Keeps redirect_uri/state in a secure httpOnly cookie across auth page navigations. */
+export function RedirectContextPersist() {
+  const searchParams = useSearchParams();
+  const redirectUri = searchParams.get("redirect_uri");
+  const state = searchParams.get("state");
+
+  useEffect(() => {
+    void PersistRedirectContext(redirectUri, state);
+  }, [redirectUri, state]);
+
+  return null;
+}

package/src/sso-config/redirect-context-route.tsx

@@ -0,0 +1,45 @@
+import { NextRequest, NextResponse } from "next/server";
+import { AUTH_COOKIES } from "./cookie-helpers";
+import { CreatePkcePair } from "./pkce-helpers";
+import {
+  CreateOAuthNonce,
+  DecodeRedirectContext,
+  IsAllowedRedirectUri,
+  SanitizeReturnPath,
+  SetRedirectContextCookie,
+} from "./redirect-context-helpers";
+
+/** Route Handler — persists redirect_uri/state in a signed cookie, then forwards to the auth sign-in page. */
+export async function RedirectContextRoute(req: NextRequest) {
+  const redirectUri = req.nextUrl.searchParams.get("redirect_uri");
+  const state = req.nextUrl.searchParams.get("state");
+
+  const signInUrl = new URL("/auth/sign-in", req.url);
+  if (redirectUri) signInUrl.searchParams.set("redirect_uri", redirectUri);
+  if (state) signInUrl.searchParams.set("state", state);
+
+  const response = NextResponse.redirect(signInUrl);
+  const trimmedUri = redirectUri?.trim();
+
+  if (!trimmedUri || !IsAllowedRedirectUri(trimmedUri)) {
+    return response;
+  }
+
+  const existing = DecodeRedirectContext(req.cookies.get(AUTH_COOKIES.redirectContext)?.value);
+  if (existing?.redirectUri === trimmedUri) {
+    SetRedirectContextCookie(response, existing);
+    return response;
+  }
+
+  const pkce = CreatePkcePair();
+  SetRedirectContextCookie(response, {
+    redirectUri: trimmedUri,
+    state: CreateOAuthNonce(),
+    returnPath: SanitizeReturnPath(state),
+    codeChallenge: pkce.challenge,
+    codeChallengeMethod: pkce.method,
+    pkceVerifier: pkce.verifier,
+  });
+
+  return response;
+}

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

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { HttpPost } from "../services/http-services";
+import { AUTH_COOKIES, GetDecryptedRequestCookie, SetAuthCookies } from "./cookie-helpers";
+import { SSO_CONFIG } from "./sso-config";
+import { SSOAuthResponse } from "./sso-interfaces";
+
+export async function RefreshRoute(req: NextRequest) {
+  const refreshToken = GetDecryptedRequestCookie(req, AUTH_COOKIES.refreshToken);
+  if (!refreshToken) return NextResponse.json({ error: "No refresh token" }, { status: 401 });
+
+  try {
+    const refreshRes = await HttpPost(SSO_CONFIG.BACKEND_ENDPOINTS.REFRESH, { refreshToken, clientSystemName: SSO_CONFIG.BACKEND_CONFIG.CLIENT_SYSTEM_NAME });
+    if (!refreshRes.isSuccess) return NextResponse.json({ error: "Refresh failed" }, { status: 401 });
+
+    const newTokens = refreshRes.result as SSOAuthResponse;
+    const response = NextResponse.json({ ok: true });
+    SetAuthCookies(response, newTokens);
+    return response;
+  } catch {
+    return NextResponse.json({ error: "Auth service unavailable" }, { status: 500 });
+  }
+}

package/src/sso-config/sign-in-route.tsx

@@ -0,0 +1,69 @@
+import { NextRequest, NextResponse } from "next/server";
+import { EErrorCodes, EExceptionCategories } from "../interfaces/exception-interfaces";
+import { GetResponse } from "../interfaces/http-interfaces";
+import { URLS } from "../nexus.environments";
+import { HttpPost } from "../services/http-services";
+import { AUTH_COOKIES, GetDecryptedRequestCookie, SetAuthCookies, SetSsoSessionCookie } from "./cookie-helpers";
+import { CreatePkcePair } from "./pkce-helpers";
+import { ClearRedirectContextCookie } from "./redirect-context-helpers";
+import { ExchangeAuthorizationCode, RequestAuthorizationCode } from "./sso-backend-flow";
+import { BuildAuthenticationSignInUrl, SSO_CONFIG } from "./sso-config";
+import { ILoginRequest, ILoginResponse } from "./sso-interfaces";
+
+function failRedirect(req: NextRequest) {
+  const returnPath = req.nextUrl.searchParams.get("state") ?? "/";
+  return NextResponse.redirect(new URL(BuildAuthenticationSignInUrl(returnPath)));
+}
+
+/** GET — exchange local sso_session for access tokens (identity provider app). */
+export async function SignInGetRoute(req: NextRequest) {
+  const ssoSession = GetDecryptedRequestCookie(req, AUTH_COOKIES.ssoSession);
+
+  if (!ssoSession) return failRedirect(req);
+
+  const pkce = CreatePkcePair();
+
+  try {
+    const code = await RequestAuthorizationCode({
+      ssoSession,
+      redirectUri: SSO_CONFIG.FRONTEND_ENDPOINTS.CALLBACK,
+      pkce,
+    });
+    if (!code) return failRedirect(req);
+
+    const tokenData = await ExchangeAuthorizationCode({
+      code,
+      redirectUri: SSO_CONFIG.FRONTEND_ENDPOINTS.CALLBACK,
+      codeVerifier: pkce.verifier,
+    });
+    if (!tokenData) return failRedirect(req);
+
+    const response = NextResponse.redirect(new URL(URLS.CURRENT!));
+    SetAuthCookies(response, tokenData);
+    ClearRedirectContextCookie(response);
+    return response;
+  } catch {
+    return failRedirect(req);
+  }
+}
+
+/** POST — username/password sign-in (identity provider app). */
+export async function SignInPostRoute(req: NextRequest) {
+  const body = (await req.json()) as ILoginRequest;
+  body.clientSystemName = SSO_CONFIG.BACKEND_CONFIG.CLIENT_SYSTEM_NAME;
+
+  if (!body.username?.trim() || !body.password) return NextResponse.json(GetResponse.ERROR("Username and password are required.", "USERNAME_AND_PASSWORD_REQUIRED", EExceptionCategories.Validation, EErrorCodes.FormatInvalid, "Username|Password"), { status: 400 });
+
+  const signInRes = await HttpPost(SSO_CONFIG.BACKEND_ENDPOINTS.SIGN_IN, body);
+
+  const signInResult = signInRes?.result as ILoginResponse;
+
+  if (signInResult?.ssoSession) signInResult.redirectUrl = SSO_CONFIG.FRONTEND_ENDPOINTS.SSO_COMPLETE;
+
+  if (!signInRes.isSuccess || !signInResult?.ssoSession) return NextResponse.json(signInRes, { status: signInRes.code ?? 401 });
+
+  const response = NextResponse.json(signInRes);
+
+  SetSsoSessionCookie(response, signInResult.ssoSession, SSO_CONFIG.BACKEND_CONFIG.SSO_SESSION_MAX_AGE);
+  return response;
+}

package/src/sso-config/sign-out-route.tsx

@@ -0,0 +1,53 @@
+import { NextRequest, NextResponse } from "next/server";
+import { NEXUS_INFO, URLS } from "../nexus.environments";
+import { HttpPost } from "../services/http-services";
+import { AUTH_COOKIES, ClearAllAuthCookies, GetDecryptedRequestCookie } from "./cookie-helpers";
+import { SanitizeReturnPath } from "./redirect-context-helpers";
+import { SSO_CONFIG } from "./sso-config";
+
+function hasAuthSession(req: NextRequest): boolean {
+  return !!(req.cookies.get(AUTH_COOKIES.ssoSession)?.value || req.cookies.get(AUTH_COOKIES.accessToken)?.value || req.cookies.get(AUTH_COOKIES.refreshToken)?.value);
+}
+
+function resolveReturnUrl(req: NextRequest): URL {
+  if (NEXUS_INFO.IS_ADMIN_MODULE && !hasAuthSession(req)) {
+    return new URL(URLS.SIGN_IN);
+  }
+
+  const appBase = req.nextUrl.origin ?? URLS.CURRENT!;
+  const returnPath = req.nextUrl.searchParams.get("returnUrl");
+  if (returnPath) {
+    return new URL(SanitizeReturnPath(returnPath), appBase);
+  }
+
+  return new URL(appBase);
+}
+
+async function revokeServerSession(req: NextRequest) {
+  const ssoSession = GetDecryptedRequestCookie(req, AUTH_COOKIES.ssoSession);
+  if (!ssoSession) return;
+
+  const response = await HttpPost(SSO_CONFIG.BACKEND_ENDPOINTS.SIGN_OUT, { ssoSession });
+
+  return response.isSuccess;
+}
+
+/** GET — clear cookies and redirect back to the originating app page. */
+export async function SignOutGetRoute(req: NextRequest) {
+  await revokeServerSession(req);
+  const response = NextResponse.redirect(resolveReturnUrl(req));
+  ClearAllAuthCookies(response);
+  return response;
+}
+
+/** POST — clear cookies and return JSON (API clients). */
+export async function SignOutPostRoute(req: NextRequest) {
+  if (NEXUS_INFO.IS_ADMIN_MODULE && !hasAuthSession(req)) {
+    return NextResponse.json({ ok: false, redirect: URLS.SIGN_IN }, { status: 401 });
+  }
+
+  await revokeServerSession(req);
+  const response = NextResponse.json({ ok: true });
+  ClearAllAuthCookies(response);
+  return response;
+}

package/src/sso-config/sign-up-route.tsx

@@ -0,0 +1,46 @@
+import { NextRequest, NextResponse } from "next/server";
+import { HttpPost } from "../services/http-services";
+import { SetSsoSessionCookie } from "./cookie-helpers";
+import { SSO_CONFIG } from "./sso-config";
+import { ISignUpRequest } from "./sso-interfaces";
+import { ParseWrappedResult } from "./sso-response-helpers";
+
+const mapGender = (gender?: string | null) => {
+  const normalized = gender?.trim().toLowerCase();
+  if (normalized === "male") return 0;
+  if (normalized === "female") return 1;
+  return 2;
+};
+
+/** POST — register a new account (identity provider app). */
+export async function SignUpPostRoute(req: NextRequest) {
+  const body = (await req.json()) as ISignUpRequest & { confirmPassword?: string };
+
+  if (!body.fullName?.trim() || !body.username?.trim() || !body.email?.trim() || !body.password || !body.confirmPassword) {
+    return NextResponse.json({ error: "All required fields must be provided." }, { status: 400 });
+  }
+
+  if (body.password !== body.confirmPassword) {
+    return NextResponse.json({ error: "Passwords do not match." }, { status: 400 });
+  }
+
+  const signUpRes = await HttpPost(SSO_CONFIG.BACKEND_ENDPOINTS.SIGN_UP, {
+    fullname: body.fullName.trim(),
+    username: body.username.trim(),
+    password: body.password,
+    confirmPassword: body.confirmPassword,
+    genderType: mapGender(body.gender),
+    emailAddress: body.email.trim(),
+    contactNumber: null,
+    clientSystemName: SSO_CONFIG.BACKEND_CONFIG.CLIENT_SYSTEM_NAME,
+  });
+
+  const signUpResult = ParseWrappedResult<{ ssoSession: string }>(signUpRes);
+  if (!signUpRes.isSuccess || !signUpResult?.ssoSession) {
+    return NextResponse.json(signUpRes, { status: signUpRes.code ?? 400 });
+  }
+
+  const response = NextResponse.json(signUpRes);
+  SetSsoSessionCookie(response, signUpResult.ssoSession, SSO_CONFIG.BACKEND_CONFIG.SSO_SESSION_MAX_AGE);
+  return response;
+}

package/src/sso-config/sso-backend-flow.ts

@@ -0,0 +1,45 @@
+import { HttpPost } from "../services/http-services";
+import { PKCE_METHOD_S256, PkcePair } from "./pkce-helpers";
+import { SSO_CONFIG } from "./sso-config";
+import { SSOAuthResponse } from "./sso-interfaces";
+import { ParseSsoCodeResponse, ParseTokenResponse } from "./sso-response-helpers";
+
+export type SsoExchangeInput = {
+  ssoSession: string;
+  redirectUri: string;
+  state?: string;
+  returnPath?: string;
+  pkce: PkcePair;
+};
+
+export type TokenExchangeInput = {
+  code: string;
+  redirectUri: string;
+  codeVerifier: string;
+};
+
+/** Server-only: request an authorization code using client policy + PKCE. */
+export async function RequestAuthorizationCode(input: SsoExchangeInput): Promise<string | null> {
+  const ssoRes = await HttpPost(SSO_CONFIG.BACKEND_ENDPOINTS.SSO, {
+    ssoSession: input.ssoSession,
+    redirectUri: input.redirectUri,
+    state: input.state,
+    returnPath: input.returnPath,
+    codeChallenge: input.pkce.challenge,
+    codeChallengeMethod: input.pkce.method ?? PKCE_METHOD_S256,
+  });
+
+  return ParseSsoCodeResponse(ssoRes);
+}
+
+/** Server-only: exchange authorization code for tokens. */
+export async function ExchangeAuthorizationCode(input: TokenExchangeInput): Promise<SSOAuthResponse | null> {
+  const tokenRes = await HttpPost(SSO_CONFIG.BACKEND_ENDPOINTS.TOKEN, {
+    code: input.code,
+    redirectUri: input.redirectUri,
+    clientSystemName: SSO_CONFIG.BACKEND_CONFIG.CLIENT_SYSTEM_NAME,
+    codeVerifier: input.codeVerifier,
+  });
+
+  return ParseTokenResponse(tokenRes);
+}

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

@@ -0,0 +1,46 @@
+import { NextRequest, NextResponse } from "next/server";
+import { AUTH_COOKIES, GetDecryptedRequestCookie } from "./cookie-helpers";
+import { EncodeOAuthCallbackState } from "./oauth-callback-state";
+import { BuildAuthenticationSignInUrl } from "./sso-config";
+import { ClearRedirectContextCookie, DecodeRedirectContext } from "./redirect-context-helpers";
+import { PKCE_METHOD_S256, PkcePair } from "./pkce-helpers";
+import { RequestAuthorizationCode } from "./sso-backend-flow";
+
+function buildSignInRedirect(redirectContext: ReturnType<typeof DecodeRedirectContext>) {
+  return new URL(BuildAuthenticationSignInUrl(redirectContext?.returnPath));
+}
+
+/** Completes SSO after credentials sign-in: exchange session for code and redirect to the client callback. */
+export async function SsoCompleteRoute(req: NextRequest) {
+  const ssoSession = GetDecryptedRequestCookie(req, AUTH_COOKIES.ssoSession);
+  const redirectContext = DecodeRedirectContext(req.cookies.get(AUTH_COOKIES.redirectContext)?.value);
+
+  if (!ssoSession || !redirectContext?.redirectUri) {
+    return NextResponse.redirect(buildSignInRedirect(redirectContext));
+  }
+
+  const pkce: PkcePair = {
+    verifier: redirectContext.pkceVerifier,
+    challenge: redirectContext.codeChallenge,
+    method: (redirectContext.codeChallengeMethod as PkcePair["method"]) ?? PKCE_METHOD_S256,
+  };
+
+  try {
+    const code = await RequestAuthorizationCode({
+      ssoSession,
+      redirectUri: redirectContext.redirectUri,
+      state: redirectContext.state,
+      returnPath: redirectContext.returnPath,
+      pkce,
+    });
+    if (!code) return NextResponse.redirect(buildSignInRedirect(redirectContext));
+
+    const callbackState = EncodeOAuthCallbackState(redirectContext.state, redirectContext.returnPath, pkce.verifier);
+    const location = `${redirectContext.redirectUri}?code=${encodeURIComponent(code)}&state=${encodeURIComponent(callbackState)}`;
+    const response = NextResponse.redirect(location);
+    ClearRedirectContextCookie(response);
+    return response;
+  } catch {
+    return NextResponse.redirect(buildSignInRedirect(redirectContext));
+  }
+}

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

@@ -0,0 +1,57 @@
+import { APIS, URLS } from "nexus-shared";
+
+const _callbackPath = `${URLS.CURRENT}/api/auth/callback`;
+
+export const SSO_CONFIG = {
+  COOKIE_CONFIG: {
+    COOKIE_SECRET: process.env.SSO_COOKIE_SECRET as string,
+  },
+  BACKEND_ENDPOINTS: {
+    SIGN_IN: `${APIS.AUTHENTICATION}/Authentication/SignIn`,
+    SIGN_UP: `${APIS.AUTHENTICATION}/Authentication/SignUp`,
+    SSO: `${APIS.AUTHENTICATION}/Authentication/SSO`,
+    TOKEN: `${APIS.AUTHENTICATION}/Authentication/Token`,
+    REFRESH: `${APIS.AUTHENTICATION}/Authentication/Refresh`,
+    SIGN_OUT: `${APIS.AUTHENTICATION}/Authentication/SignOut`,
+    PROVIDERS: `${APIS.AUTHENTICATION}/Authentication/Providers`,
+    FORGOT_PASSWORD: `${APIS.AUTHENTICATION}/Authentication/ForgotPassword`,
+    RESET_PASSWORD: `${APIS.AUTHENTICATION}/Authentication/ResetPassword`,
+    /** Used by VerifyAccessToken — returns 200 for a valid Bearer token, 401 otherwise. */
+    VERIFY: `${APIS.AUTHENTICATION}/Authentication/Verify`,
+    PROVIDER_CHALLENGE: (provider: string, returnUrl: string, clientSystemName: string) => `${APIS.AUTHENTICATION}/Provider/${provider}/Challenge?returnUrl=${encodeURIComponent(returnUrl)}&clientSystemName=${encodeURIComponent(clientSystemName)}`,
+  },
+  BACKEND_CONFIG: {
+    /** Matches AuthenticationOptions.DefaultClientSystemName (NEXUS_WEB_APPLICATION_API). */
+    CLIENT_SYSTEM_NAME: process.env.AUTH_CLIENT_SYSTEM_NAME as string,
+    /** Matches ClientApplications.SsoSessionLifetime (30 minutes). */
+    SSO_SESSION_MAX_AGE: process.env.SSO_SESSION_MAX_AGE as string,
+    /** How long redirect_uri/state survive in a secure httpOnly cookie on the auth app (seconds). */
+    REDIRECT_CONTEXT_MAX_AGE: process.env.REDIRECT_CONTEXT_MAX_AGE as string,
+  },
+  FRONTEND_ENDPOINTS: {
+    CALLBACK: _callbackPath,
+    SIGN_IN: `${URLS.CURRENT}/api/auth/sign-in`,
+    SIGN_UP: `${URLS.CURRENT}/api/auth/sign-up`,
+    SIGN_OUT: `${URLS.CURRENT}/api/auth/sign-out`,
+    REFRESH: `${URLS.CURRENT}/api/auth/refresh`,
+    SSO_COMPLETE: `${URLS.CURRENT}/api/auth/sso-complete`,
+    PROVIDER_COMPLETE: `${URLS.CURRENT}/api/auth/provider-complete`,
+    FORGOT_PASSWORD: `${URLS.CURRENT}/api/auth/forgot-password`,
+    RESET_PASSWORD: `${URLS.CURRENT}/api/auth/reset-password`,
+  },
+} as const;
+
+/** Client-app entry URL for centralized sign-in (includes redirect_uri + optional return path). */
+export function BuildAuthenticationSignInUrl(returnPath?: string) {
+  const entryUrl = new URL(`${URLS.AUTHENTICATION}/api/auth/redirect-context`);
+  entryUrl.searchParams.set("redirect_uri", SSO_CONFIG.FRONTEND_ENDPOINTS.CALLBACK);
+  if (returnPath) entryUrl.searchParams.set("state", returnPath);
+  return entryUrl.toString();
+}
+
+/** Sign-out URL that returns the user to a page on this app after cookies are cleared. */
+export function BuildSignOutUrl(returnPath?: string) {
+  const signOutUrl = new URL(SSO_CONFIG.FRONTEND_ENDPOINTS.SIGN_OUT);
+  if (returnPath) signOutUrl.searchParams.set("returnUrl", returnPath);
+  return signOutUrl.toString();
+}

package/src/{interfaces → sso-config}/sso-interfaces.tsx

@@ -1,4 +1,4 @@
-import { UN } from "nexus-shared";
+import { UN } from "../interfaces/type-interfaces";
 export interface SSOAuthResponse {
   accessToken: string;
   refreshToken: string;
@@ -19,6 +19,11 @@ export interface IRedirectContext {
   state: string;
   /** Relative path to return to after sign-in completes. */
   returnPath: string;
+  /** PKCE code challenge (stored server-side until SSO). */
+  codeChallenge: string;
+  codeChallengeMethod: string;
+  /** PKCE verifier (server-side only; also embedded in signed callback state). */
+  pkceVerifier: string;
 }
 
 export interface ISignInParams {
@@ -33,6 +38,8 @@ export interface ISsoSessionResponse {
 export interface ILoginRequest {
   username: string;
   password: string;
+  rememberMe: boolean;
+  clientSystemName: string;
 }
 
 export interface ILoginResponse {
@@ -40,6 +47,15 @@ export interface ILoginResponse {
   displayName: string;
   role: string;
   userId: number;
+  redirectUrl?: string;
+}
+
+export interface ISignUpRequest {
+  fullName: string;
+  gender?: string | UN;
+  username: string;
+  email: string;
+  password: string;
 }
 
 export interface IDemoUserInfo {