feat(FR-2630): add useSToken hook with nuqs and stoken deprecation warning

Centralize the URL query parameter lookup for sToken-based SSO entry
points. The hook returns [effective, clear] where effective prefers the
canonical sToken key over the deprecated lowercase stoken alias, and
clear nulls both keys so successful logins strip the token from the URL
without leaking either form.

A single logger.warn fires per hook instance (via useEffectEvent + ref
guard) when only stoken is present, preparing a future hard-deprecation
without interfering with the current hybrid acceptance rule.

The boundary component (FR-2631) and its route wrappers (FR-2636,
FR-2641) consume this hook instead of reading from window.location
directly; see spec section URL 파라미터 파싱 규약 (nuqs).

Refs FR-2616

Author: nowgnuesLee

react/src/hooks/useSToken.ts

@@ -0,0 +1,66 @@
+/**
+ @license
+ Copyright (c) 2015-2026 Lablup Inc. All rights reserved.
+ */
+import { useBAILogger } from 'backend.ai-ui';
+import { parseAsString, useQueryState } from 'nuqs';
+import { useCallback, useEffect, useEffectEvent, useRef } from 'react';
+
+/**
+ * Read and clear the sToken URL query parameter using nuqs.
+ *
+ * The `STokenLoginBoundary` component (Epic FR-2616) intentionally does not
+ * read from `window.location` on its own — callers must source `sToken` via
+ * nuqs and pass it as a prop. This hook centralizes that lookup so the two
+ * call sites (LoginView route wrapper, EduAppLauncher route wrapper) and any
+ * future token URL entry point share the same canonical-vs-deprecated
+ * handling.
+ *
+ * Resolution:
+ *   1. `?sToken=...` (canonical key) takes precedence.
+ *   2. `?stoken=...` (deprecated lowercase alias) is accepted as a fallback.
+ *      A single deprecation warning is logged per hook instance when only
+ *      `stoken` is present.
+ *
+ * The returned `clear` setter nulls both keys so the tuple is safe to call
+ * from `STokenLoginBoundary`'s `onSuccess` callback without leaking either
+ * form of the token into browser history or referers.
+ */
+
+export const useSToken = (): [
+  string | null,
+  (next: string | null) => Promise<URLSearchParams>,
+] => {
+  'use memo';
+  const { logger } = useBAILogger();
+  const [sToken, setSToken] = useQueryState('sToken', parseAsString);
+  const [stoken, setStoken] = useQueryState('stoken', parseAsString);
+  const hasWarnedRef = useRef(false);
+
+  const logDeprecationIfNeeded = useEffectEvent(() => {
+    if (stoken && !sToken && !hasWarnedRef.current) {
+      hasWarnedRef.current = true;
+      logger.warn(
+        'Query parameter `stoken` (lowercase) is deprecated; use `sToken`.',
+      );
+    }
+  });
+
+  useEffect(() => {
+    logDeprecationIfNeeded();
+  }, [sToken, stoken]);
+
+  const clear = useCallback(
+    async (next: string | null) => {
+      // Clear both keys; callers typically pass `null` after a successful
+      // login to strip the token from the URL. Return the final search
+      // params from the last setter to match nuqs' Promise contract.
+      await setSToken(next);
+      return setStoken(null);
+    },
+    [setSToken, setStoken],
+  );
+
+  const effective = sToken ?? stoken;
+  return [effective, clear];
+};