api auth

2026-06-01 00:47:26 +04:00
parent 49f69f6af0
commit 4d8dc6b59c
22 changed files with 1266 additions and 353 deletions
--- a/src/app/components/telegram-login/telegram-login.component.html
+++ b/src/app/components/telegram-login/telegram-login.component.html
@@ -29,6 +29,12 @@
          {{ 'auth.loginWithTelegram' | translate }}
        </button>

+        @if (loginUrl()) {
+          <a class="bot-link" [href]="loginUrl()" target="_blank" rel="noopener noreferrer">
+            {{ loginUrl() }}
+          </a>
+        }
+
        <div class="qr-section">
          <p class="qr-hint">{{ 'auth.orScanQr' | translate }}</p>

@@ -57,12 +63,12 @@
              </div>
            }
            @case ('error') {
-              <div class="qr-container">
-                <img [src]="'https://api.qrserver.com/v1/create-qr-code/?size=180x180&data=' + encodedQrUrl()"
-                     alt="QR Code"
-                     width="180"
-                     height="180"
-                     loading="lazy" />
+              <div class="qr-container qr-error" (click)="refreshQr()">
+                <svg width="32" height="32" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                  <path d="M1 4v6h6M23 20v-6h-6"/>
+                  <path d="M20.49 9A9 9 0 0 0 5.64 5.64L1 10m22 4l-4.64 4.36A9 9 0 0 1 3.51 15"/>
+                </svg>
+                <span>{{ 'auth.qrError' | translate }}</span>
              </div>
            }
          }
--- a/src/app/components/telegram-login/telegram-login.component.scss
+++ b/src/app/components/telegram-login/telegram-login.component.scss
@@ -102,6 +102,20 @@ h2 {
  }
 }

+.bot-link {
+  display: block;
+  margin-top: 10px;
+  color: var(--accent-color, #497671);
+  font-size: 12px;
+  line-height: 1.35;
+  overflow-wrap: anywhere;
+  text-decoration: none;
+
+  &:hover {
+    text-decoration: underline;
+  }
+}
+
 .qr-section {
  margin-top: 20px;

@@ -158,6 +172,26 @@ h2 {
        font-size: 13px;
      }
    }
+
+    &.qr-error {
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      gap: 8px;
+      width: 204px;
+      height: 204px;
+      cursor: pointer;
+      color: var(--text-secondary, #999);
+      transition: color 0.2s ease;
+
+      &:hover {
+        color: var(--accent-color, #497671);
+      }
+
+      span {
+        font-size: 13px;
+      }
+    }
  }
 }

--- a/src/app/components/telegram-login/telegram-login.component.ts
+++ b/src/app/components/telegram-login/telegram-login.component.ts
@@ -19,10 +19,11 @@ export class TelegramLoginComponent implements OnDestroy {
  status = this.authService.status;

  loginUrl = signal('');
-  qrToken = signal('');
+  webSessionID = signal('');
  qrStatus = signal<'loading' | 'ready' | 'expired' | 'error'>('loading');
  encodedQrUrl = computed(() => encodeURIComponent(this.loginUrl()));

+  private readonly pollIntervalMs = 5000;
  private pollTimer?: ReturnType<typeof setInterval>;

  constructor() {
@@ -45,12 +46,14 @@ export class TelegramLoginComponent implements OnDestroy {
  }

  openTelegramLogin(): void {
-    window.open(this.loginUrl(), '_blank');
+    const url = this.loginUrl();
+    if (!url) return;
+
+    window.open(url, '_blank');
    if (!this.pollTimer) {
-      if (this.qrToken()) {
-        this.startPolling(this.qrToken());
-      } else {
-        this.startSessionPolling();
+      const webSessionID = this.webSessionID();
+      if (webSessionID) {
+        this.startPolling(webSessionID);
      }
    }
  }
@@ -62,43 +65,25 @@ export class TelegramLoginComponent implements OnDestroy {

  private initQrLogin(): void {
    this.qrStatus.set('loading');
-    this.authService.createQrToken().subscribe({
+    this.loginUrl.set('');
+    this.webSessionID.set('');
+
+    this.authService.createWebSession().subscribe({
      next: (res) => {
        this.loginUrl.set(res.url);
-        this.qrToken.set(res.token);
+        this.webSessionID.set(res.webSessionID);
        this.qrStatus.set('ready');
-        this.startPolling(res.token);
+        this.startPolling(res.webSessionID);
      },
      error: () => {
-        this.loginUrl.set(this.authService.getTelegramLoginUrl());
        this.qrStatus.set('error');
-        this.startSessionPolling();
      }
    });
  }

-  private startSessionPolling(): void {
+  private startPolling(webSessionID: string): void {
    this.stopPolling();
-    let checks = 0;
-    this.pollTimer = setInterval(() => {
-      checks++;
-      if (checks > 100) {
-        this.stopPolling();
-        this.qrStatus.set('expired');
-        return;
-      }
-      this.authService.checkSessionOnce().subscribe(session => {
-        if (session && session.active) {
-          this.stopPolling();
-          this.syncCartAndComplete(session.sessionId);
-        }
-      });
-    }, 3000);
-  }
-
-  private startPolling(token: string): void {
-    this.stopPolling();
-    if (!token) return;
+    if (!webSessionID) return;

    let checks = 0;
    this.pollTimer = setInterval(() => {
@@ -109,28 +94,18 @@ export class TelegramLoginComponent implements OnDestroy {
        return;
      }

-      this.authService.pollQrToken(token).subscribe({
-        next: (res) => {
-          switch (res.status) {
-            case 'confirmed':
-              this.stopPolling();
-              if (res.session) {
-                this.syncCartAndComplete(res.session.sessionId);
-              } else {
-                this.authService.onTelegramLoginComplete();
-              }
-              break;
-            case 'expired':
-              this.stopPolling();
-              this.qrStatus.set('expired');
-              break;
+      this.authService.checkSessionOnce(webSessionID).subscribe({
+        next: (session) => {
+          if (session?.active) {
+            this.stopPolling();
+            this.syncCartAndComplete(session.sessionId);
          }
        },
        error: () => {
          // Network error — keep polling
        }
      });
-    }, 3000);
+    }, this.pollIntervalMs);
  }

  private syncCartAndComplete(sessionId: string): void {
--- a/src/app/i18n/en.ts
+++ b/src/app/i18n/en.ts
@@ -206,5 +206,6 @@ export const en: Translations = {
    orScanQr: 'Or scan the QR code',
    loginNote: 'You will be redirected back after login',
    qrExpired: 'QR code expired. Click to refresh',
+    qrError: 'Could not create login session. Click to retry',
  },
 };
--- a/src/app/i18n/hy.ts
+++ b/src/app/i18n/hy.ts
@@ -206,5 +206,6 @@ export const hy: Translations = {
    orScanQr: 'Կամ սքանավորեք QR կոդը',
    loginNote: 'Մուտքից հետո դուք կվերաուղղվեք',
    qrExpired: 'QR կոդը հնացել է։ Սեղմեք՝ թարմացնելու համար',
+    qrError: 'Չհաջողվեց ստեղծել մուտքի սեսիա։ Սեղմեք՝ կրկնելու համար',
  },
 };
--- a/src/app/i18n/ru.ts
+++ b/src/app/i18n/ru.ts
@@ -206,5 +206,6 @@ export const ru: Translations = {
    orScanQr: 'Или отсканируйте QR-код',
    loginNote: 'После входа вы будете перенаправлены обратно',
    qrExpired: 'QR-код устарел. Нажмите, чтобы обновить',
+    qrError: 'Не удалось создать сессию входа. Нажмите, чтобы повторить',
  },
 };
--- a/src/app/i18n/translations.ts
+++ b/src/app/i18n/translations.ts
@@ -204,5 +204,6 @@ export interface Translations {
    orScanQr: string;
    loginNote: string;
    qrExpired: string;
+    qrError: string;
  };
 }
--- a/src/app/interceptors/mock-data.interceptor.ts
+++ b/src/app/interceptors/mock-data.interceptor.ts
@@ -672,7 +672,7 @@ function respond<T>(body: T, delayMs = 150) {
 }

 // ─── Mock Auth State ───
-let mockQrPollCount = 0;
+const mockWebSessionChecks = new Map<string, number>();

 // ─── The Interceptor ───

@@ -688,38 +688,39 @@ export const mockDataInterceptor: HttpInterceptorFn = (req, next) => {
    return respond({ message: 'pong (mock)' });
  }

-  // ── GET /auth/session
-  if (url.includes('/auth/session') && req.method === 'GET') {
-    return respond({ active: false }, 100);
+  // ── POST /users/sessions
+  if (url.endsWith('/users/sessions') && req.method === 'POST') {
+    const body = req.body as { webSessionID?: string } | null;
+    const webSessionID = body?.webSessionID || req.headers.get('WebSessionID') || 'mock-web-session';
+    mockWebSessionChecks.set(webSessionID, 0);
+    return respond({ webSessionID, status: false }, 200);
  }

-  // ── POST /auth/qr/create
-  if (url.includes('/auth/qr/create') && req.method === 'POST') {
-    const token = 'mock-qr-token-' + Date.now();
-    const botUsername = (environment as Record<string, unknown>)['telegramBot'] as string || 'DexarSupport_bot';
-    mockQrPollCount = 0;
-    return respond({
-      token,
-      url: `https://t.me/${botUsername}?start=qr_${token}`
-    }, 200);
-  }
+  // ── GET /users/sessions/:webSessionID
+  const userSessionMatch = url.match(/\/users\/sessions\/([^/?]+)$/);
+  if (userSessionMatch && req.method === 'GET') {
+    const webSessionID = decodeURIComponent(userSessionMatch[1]);
+    const checks = (mockWebSessionChecks.get(webSessionID) ?? 0) + 1;
+    mockWebSessionChecks.set(webSessionID, checks);

-  // ── GET /auth/qr/poll
-  if (url.includes('/auth/qr/poll') && req.method === 'GET') {
-    mockQrPollCount++;
-    // Simulate confirmed after 3 polls (~9 seconds)
-    if (mockQrPollCount >= 3) {
+    if (checks >= 3) {
      return respond({
-        status: 'confirmed',
-        session: {
-          sessionId: 'mock-session-' + Date.now(),
-          active: true,
-          displayName: 'Telegram User',
-          expiresAt: new Date(Date.now() + 3600000).toISOString()
-        }
+        webSessionID,
+        status: true,
+        telegramUserID: 123456,
+        username: 'telegram_user',
+        displayName: 'Telegram User',
+        expiresAt: new Date(Date.now() + 3600000).toISOString()
      }, 200);
    }
-    return respond({ status: 'pending' }, 200);
+
+    return respond({ webSessionID, status: false }, 200);
+  }
+
+  // ── DELETE /users/sessions/:webSessionID
+  if (userSessionMatch && req.method === 'DELETE') {
+    mockWebSessionChecks.delete(decodeURIComponent(userSessionMatch[1]));
+    return respond({ status: true }, 100);
  }

  // ── GET /category (all categories flat list)
--- a/src/app/models/auth.model.ts
+++ b/src/app/models/auth.model.ts
@@ -7,6 +7,11 @@ export interface AuthSession {
  expiresAt: string;
 }

+export interface WebSessionStart {
+  webSessionID: string;
+  url: string;
+}
+
 export interface TelegramAuthData {
  id: number;
  first_name: string;
@@ -17,9 +22,4 @@ export interface TelegramAuthData {
  hash: string;
 }

-export interface QrPollResponse {
-  status: 'pending' | 'confirmed' | 'expired';
-  session?: AuthSession;
-}
-
 export type AuthStatus = 'unknown' | 'checking' | 'authenticated' | 'expired' | 'unauthenticated';
--- a/src/app/pages/cart/cart.component.html
+++ b/src/app/pages/cart/cart.component.html
@@ -169,17 +169,6 @@
              </svg>
              {{ 'cart.loginWithTelegram' | translate }}
            </button>
-
-            <div class="login-gate-qr">
-              <p class="qr-hint">{{ 'cart.orScanQr' | translate }}</p>
-              <div class="qr-wrapper">
-                <img [src]="'https://api.qrserver.com/v1/create-qr-code/?size=150x150&data=' + loginUrl()" 
-                     alt="QR Code" 
-                     width="150" 
-                     height="150" 
-                     loading="lazy" />
-              </div>
-            </div>
          </div>
        }
      </div>
--- a/src/app/pages/cart/cart.component.scss
+++ b/src/app/pages/cart/cart.component.scss
@@ -802,29 +802,6 @@
        box-shadow: 0 4px 12px rgba(42, 171, 238, 0.3);
      }
    }
-
-    .login-gate-qr {
-      margin-top: 14px;
-
-      .qr-hint {
-        margin: 0 0 8px;
-        font-size: 0.8rem;
-        color: #999;
-      }
-
-      .qr-wrapper {
-        display: inline-flex;
-        padding: 10px;
-        background: #fff;
-        border-radius: 10px;
-        border: 1px solid #e5e7eb;
-
-        img {
-          display: block;
-          border-radius: 4px;
-        }
-      }
-    }
  }
 }

@@ -967,29 +944,6 @@
        box-shadow: 0 4px 12px rgba(42, 171, 238, 0.3);
      }
    }
-
-    .login-gate-qr {
-      margin-top: 14px;
-
-      .qr-hint {
-        margin: 0 0 8px;
-        font-size: 0.8rem;
-        color: #9ca3af;
-      }
-
-      .qr-wrapper {
-        display: inline-flex;
-        padding: 10px;
-        background: #fff;
-        border-radius: 12px;
-        border: 1px solid #e5e7eb;
-
-        img {
-          display: block;
-          border-radius: 4px;
-        }
-      }
-    }
  }
 }

--- a/src/app/pages/cart/cart.component.ts
+++ b/src/app/pages/cart/cart.component.ts
@@ -33,7 +33,6 @@ export class CartComponent implements OnDestroy {
  private authService = inject(AuthService);
  
  isAuthenticated = this.authService.isAuthenticated;
-  loginUrl = signal('');

  // Swipe state
  swipedItemId = signal<number | null>(null);
@@ -69,7 +68,6 @@ export class CartComponent implements OnDestroy {
    this.items = this.cartService.items;
    this.itemCount = this.cartService.itemCount;
    this.totalPrice = this.cartService.totalPrice;
-    this.loginUrl.set(this.authService.getTelegramLoginUrl());
  }

  requestLogin(): void {
--- a/src/app/services/auth.service.ts
+++ b/src/app/services/auth.service.ts
@@ -1,9 +1,12 @@
 import { Injectable, signal, computed } from '@angular/core';
 import { HttpClient } from '@angular/common/http';
 import { Observable, of, catchError, map, tap } from 'rxjs';
-import { AuthSession, AuthStatus, QrPollResponse } from '../models/auth.model';
+import { AuthSession, AuthStatus, WebSessionStart } from '../models/auth.model';
 import { environment } from '../../environments/environment';

+const WEB_SESSION_COOKIE = 'webSessionID';
+const WEB_SESSION_COOKIE_MAX_AGE_SECONDS = 60 * 60;
+
@Injectable({
  providedIn: 'root'
 })
@@ -24,52 +27,45 @@ export class AuthService {
  readonly displayName = computed(() => this.sessionSignal()?.displayName ?? null);

  private readonly apiUrl = environment.apiUrl;
-  private sessionCheckTimer?: ReturnType<typeof setInterval>;
+  private readonly authApiUrl = environment.authApiUrl;
+  private sessionCheckTimer?: ReturnType<typeof setTimeout>;

  constructor(private http: HttpClient) {
    // On init, check existing session via cookie
    this.checkSession();
  }

-  /**
-   * Check current session status with backend.
-   * The backend reads the session cookie and returns the session info.
-   */
+  /** Check the current webSessionID cookie against the auth backend. */
  checkSession(): void {
+    const webSessionID = this.getStoredWebSessionID();
+
+    if (!webSessionID) {
+      this.clearAuthState('unauthenticated');
+      return;
+    }
+
    this.statusSignal.set('checking');

-    this.http.get<AuthSession>(`${this.apiUrl}/auth/session`, {
-      withCredentials: true
-    }).pipe(
-      catchError(() => {
-        this.statusSignal.set('unauthenticated');
-        this.sessionSignal.set(null);
-        return of(null);
-      })
-    ).subscribe(session => {
-      if (session && session.active) {
-        this.sessionSignal.set(session);
-        this.statusSignal.set('authenticated');
-        this.scheduleSessionRefresh(session.expiresAt);
-      } else if (session && !session.active) {
-        this.sessionSignal.set(null);
-        this.statusSignal.set('expired');
-      } else {
-        this.statusSignal.set('unauthenticated');
+    this.checkSessionOnce(webSessionID).subscribe(session => {
+      if (!session?.active) {
+        this.clearAuthState('unauthenticated');
      }
    });
  }

  /** Check session without updating internal state (for polling) */
-  checkSessionOnce(): Observable<AuthSession | null> {
-    return this.http.get<AuthSession>(`${this.apiUrl}/auth/session`, {
-      withCredentials: true
-    }).pipe(
+  checkSessionOnce(webSessionID = this.getStoredWebSessionID()): Observable<AuthSession | null> {
+    if (!webSessionID) {
+      return of(null);
+    }
+
+    return this.http.get<Record<string, unknown>>(
+      `${this.authApiUrl}/users/sessions/${encodeURIComponent(webSessionID)}`
+    ).pipe(
+      map(response => this.normalizeWebSession(response, webSessionID)),
      tap(session => {
-        if (session && session.active) {
-          this.sessionSignal.set(session);
-          this.statusSignal.set('authenticated');
-          this.scheduleSessionRefresh(session.expiresAt);
+        if (session?.active) {
+          this.activateSession(session);
        }
      }),
      catchError(() => of(null))
@@ -78,19 +74,19 @@ export class AuthService {

  /**
   * Called after user completes Telegram login.
-   * The callback URL from Telegram will hit our backend which sets the cookie.
-   * Then we re-check the session.
   */
  onTelegramLoginComplete(): void {
-    this.checkSession();
    this.hideLogin();
+
+    if (!this.isAuthenticated()) {
+      this.checkSession();
+    }
  }

  /** Generate the Telegram login URL for bot-based auth */
-  getTelegramLoginUrl(): string {
+  getTelegramLoginUrl(webSessionID = this.generateGuid()): string {
    const botUsername = (environment as Record<string, unknown>)['telegramBot'] as string || 'DexarSupport_bot';
-    const callbackUrl = encodeURIComponent(`${this.apiUrl}/auth/telegram/callback`);
-    return `https://t.me/${botUsername}?start=auth_${callbackUrl}`;
+    return `https://t.me/${botUsername}?start=${encodeURIComponent(webSessionID)}`;
  }

  /** Get QR code data URL for Telegram login */
@@ -98,23 +94,22 @@ export class AuthService {
    return this.getTelegramLoginUrl();
  }

-  /** Create a one-time QR login token via backend */
-  createQrToken(): Observable<{ token: string; url: string }> {
-    return this.http.post<{ token: string; url: string }>(
-      `${this.apiUrl}/auth/qr/create`,
-      {},
-      { withCredentials: true }
-    );
-  }
+  /** Create a backend web session and return the Telegram start link for it. */
+  createWebSession(): Observable<WebSessionStart> {
+    const webSessionID = this.generateGuid();

-  /** Poll the QR token status (pending → confirmed / expired) */
-  pollQrToken(token: string): Observable<QrPollResponse> {
-    return this.http.get<QrPollResponse>(
-      `${this.apiUrl}/auth/qr/poll`,
-      {
-        params: { token },
-        withCredentials: true,
-      }
+    return this.http.post<Record<string, unknown>>(
+      `${this.authApiUrl}/users/sessions`,
+      { webSessionID },
+      { headers: { WebSessionID: webSessionID } }
+    ).pipe(
+      map(response => {
+        const responseWebSessionID = this.extractSessionId(response, webSessionID);
+        return {
+          webSessionID: responseWebSessionID,
+          url: this.getTelegramLoginUrl(responseWebSessionID),
+        };
+      })
    );
  }

@@ -138,17 +133,36 @@ export class AuthService {

  /** Logout — clears session on backend and locally */
  logout(): void {
-    this.http.post(`${this.apiUrl}/auth/logout`, {}, {
-      withCredentials: true
+    const webSessionID = this.sessionSignal()?.sessionId || this.getStoredWebSessionID();
+
+    if (!webSessionID) {
+      this.clearAuthState('unauthenticated');
+      return;
+    }
+
+    this.http.delete(`${this.authApiUrl}/users/sessions/${encodeURIComponent(webSessionID)}`, {
+      headers: { WebSessionID: webSessionID }
    }).pipe(
      catchError(() => of(null))
    ).subscribe(() => {
-      this.sessionSignal.set(null);
-      this.statusSignal.set('unauthenticated');
-      this.clearSessionRefresh();
+      this.clearAuthState('unauthenticated');
    });
  }

+  private activateSession(session: AuthSession): void {
+    this.sessionSignal.set(session);
+    this.statusSignal.set('authenticated');
+    this.setStoredWebSessionID(session.sessionId);
+    this.scheduleSessionRefresh(session.expiresAt);
+  }
+
+  private clearAuthState(status: AuthStatus): void {
+    this.sessionSignal.set(null);
+    this.statusSignal.set(status);
+    this.clearStoredWebSessionID();
+    this.clearSessionRefresh();
+  }
+
  /** Schedule a session re-check before it expires */
  private scheduleSessionRefresh(expiresAt: string): void {
    this.clearSessionRefresh();
@@ -156,7 +170,9 @@ export class AuthService {
    const expiresMs = new Date(expiresAt).getTime();
    const nowMs = Date.now();
    // Re-check 60 seconds before expiry, minimum 30s from now
-    const refreshIn = Math.max(expiresMs - nowMs - 60_000, 30_000);
+    const refreshIn = Number.isFinite(expiresMs)
+      ? Math.max(expiresMs - nowMs - 60_000, 30_000)
+      : WEB_SESSION_COOKIE_MAX_AGE_SECONDS * 1000;

    this.sessionCheckTimer = setTimeout(() => {
      this.checkSession();
@@ -169,4 +185,176 @@ export class AuthService {
      this.sessionCheckTimer = undefined;
    }
  }
+
+  private normalizeWebSession(response: Record<string, unknown> | null, fallbackSessionId: string): AuthSession | null {
+    if (!response) {
+      return null;
+    }
+
+    const user = this.asRecord(this.readFirst(response, ['user', 'User', 'telegramUser', 'TelegramUser'])) ?? response;
+    const status = this.readFirst(response, [
+      'status',
+      'Status',
+      'active',
+      'Active',
+      'loggedIn',
+      'LoggedIn',
+      'isLoggedIn',
+      'IsLoggedIn',
+      'authenticated',
+      'Authenticated'
+    ]);
+    const active = this.isActiveStatus(status);
+    const sessionId = this.extractSessionId(response, fallbackSessionId);
+    const username = this.readString(this.readFirst(user, ['username', 'Username']))
+      ?? this.readString(this.readFirst(response, ['username', 'Username']));
+    const firstName = this.readString(this.readFirst(user, ['firstName', 'first_name', 'FirstName', 'First_name']));
+    const lastName = this.readString(this.readFirst(user, ['lastName', 'last_name', 'LastName', 'Last_name']));
+    const fullName = [firstName, lastName].filter(Boolean).join(' ');
+    const explicitDisplayName = this.readString(this.readFirst(response, ['displayName', 'DisplayName', 'name', 'Name']))
+      ?? this.readString(this.readFirst(user, ['displayName', 'DisplayName', 'name', 'Name']))
+    const displayName = explicitDisplayName ?? username ?? (fullName || 'Telegram User');
+    const telegramUserId = this.readNumber(this.readFirst(user, ['telegramUserId', 'telegramUserID', 'TelegramUserID', 'id', 'ID']))
+      ?? this.readNumber(this.readFirst(response, ['telegramUserId', 'telegramUserID', 'TelegramUserID', 'userID', 'UserID']))
+      ?? 0;
+    const expiresAt = this.readString(this.readFirst(response, ['expiresAt', 'ExpiresAt', 'expires', 'Expires']))
+      ?? new Date(Date.now() + WEB_SESSION_COOKIE_MAX_AGE_SECONDS * 1000).toISOString();
+
+    return {
+      sessionId,
+      telegramUserId,
+      username,
+      displayName,
+      active,
+      expiresAt,
+    };
+  }
+
+  private extractSessionId(response: Record<string, unknown> | null, fallbackSessionId: string): string {
+    if (!response) {
+      return fallbackSessionId;
+    }
+
+    return this.readString(this.readFirst(response, [
+      'webSessionID',
+      'WebSessionID',
+      'webSessionId',
+      'sessionID',
+      'SessionID',
+      'sessionId',
+      'id',
+      'ID'
+    ])) ?? fallbackSessionId;
+  }
+
+  private readFirst(source: Record<string, unknown>, keys: string[]): unknown {
+    for (const key of keys) {
+      if (Object.prototype.hasOwnProperty.call(source, key)) {
+        return source[key];
+      }
+    }
+
+    return undefined;
+  }
+
+  private readString(value: unknown): string | null {
+    if (typeof value === 'string' && value.trim()) {
+      return value;
+    }
+
+    if (typeof value === 'number' || typeof value === 'bigint') {
+      return value.toString();
+    }
+
+    return null;
+  }
+
+  private readNumber(value: unknown): number | null {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+      return value;
+    }
+
+    if (typeof value === 'string') {
+      const parsed = Number(value);
+      return Number.isFinite(parsed) ? parsed : null;
+    }
+
+    return null;
+  }
+
+  private asRecord(value: unknown): Record<string, unknown> | null {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+      ? value as Record<string, unknown>
+      : null;
+  }
+
+  private isActiveStatus(status: unknown): boolean {
+    if (status === true || status === 1) {
+      return true;
+    }
+
+    if (typeof status !== 'string') {
+      return false;
+    }
+
+    return ['true', '1', 'active', 'authenticated', 'confirmed', 'success', 'logged_in'].includes(status.toLowerCase());
+  }
+
+  private generateGuid(): string {
+    if (globalThis.crypto?.randomUUID) {
+      return globalThis.crypto.randomUUID();
+    }
+
+    const bytes = new Uint8Array(16);
+    if (globalThis.crypto?.getRandomValues) {
+      globalThis.crypto.getRandomValues(bytes);
+    } else {
+      for (let index = 0; index < bytes.length; index++) {
+        bytes[index] = Math.floor(Math.random() * 256);
+      }
+    }
+
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+
+    const hex = Array.from(bytes, byte => byte.toString(16).padStart(2, '0'));
+    return `${hex.slice(0, 4).join('')}-${hex.slice(4, 6).join('')}-${hex.slice(6, 8).join('')}-${hex.slice(8, 10).join('')}-${hex.slice(10, 16).join('')}`;
+  }
+
+  private getStoredWebSessionID(): string | null {
+    if (typeof document === 'undefined') {
+      return null;
+    }
+
+    const cookie = document.cookie
+      .split('; ')
+      .find(row => row.startsWith(`${WEB_SESSION_COOKIE}=`));
+
+    if (!cookie) {
+      return null;
+    }
+
+    try {
+      return decodeURIComponent(cookie.substring(WEB_SESSION_COOKIE.length + 1));
+    } catch {
+      return null;
+    }
+  }
+
+  private setStoredWebSessionID(webSessionID: string): void {
+    if (typeof document === 'undefined') {
+      return;
+    }
+
+    const secure = typeof window !== 'undefined' && window.location.protocol === 'https:' ? '; Secure' : '';
+    document.cookie = `${WEB_SESSION_COOKIE}=${encodeURIComponent(webSessionID)}; Max-Age=${WEB_SESSION_COOKIE_MAX_AGE_SECONDS}; Path=/; SameSite=Lax${secure}`;
+  }
+
+  private clearStoredWebSessionID(): void {
+    if (typeof document === 'undefined') {
+      return;
+    }
+
+    document.cookie = `${WEB_SESSION_COOKIE}=; Max-Age=0; Path=/; SameSite=Lax`;
+  }
 }