rystem.authentication.social.client 0.5.0

package/lib/services/NextAppRouterRoutingService.example.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * Unified Routing Service for Next.js App Router (v13+)
+ *
+ * This service handles both URL parameter reading and navigation for Next.js with App Router.
+ * Copy this file to your project and remove the `.example` extension.
+ *
+ * IMPORTANT: This must be used in Client Components ('use client')
+ *
+ * @example
+ * ```typescript
+ * 'use client';
+ *
+ * import { NextAppRouterRoutingService } from './NextAppRouterRoutingService';
+ * import { useRouter, usePathname, useSearchParams } from 'next/navigation';
+ *
+ * const routingService = new NextAppRouterRoutingService();
+ *
+ * setupSocialLogin(x => {
+ *     x.routingService = routingService;
+ * });
+ *
+ * export default function LoginPage() {
+ *     const router = useRouter();
+ *     const pathname = usePathname();
+ *     const searchParams = useSearchParams();
+ *
+ *     useEffect(() => {
+ *         // Single initialization with all hooks
+ *         routingService.initialize(router, pathname, searchParams);
+ *     }, [router, pathname, searchParams]);
+ *
+ *     return <div>Your login page</div>;
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NextAppRouterRoutingService = void 0;
+/**
+ * Routing Service for Next.js App Router (v13+)
+ * Uses useRouter, usePathname, and useSearchParams from next/navigation
+ *
+ * NOTE: Only works in Client Components ('use client' directive required)
+ */
+class NextAppRouterRoutingService {
+    router = null;
+    pathname = null;
+    searchParams = null;
+    /**
+     * Initialize with Next.js navigation hooks
+     * MUST be called inside a Client Component ('use client')
+     *
+     * @param router - The router from useRouter() hook
+     * @param pathname - The pathname from usePathname() hook
+     * @param searchParams - The searchParams from useSearchParams() hook
+     *
+     * @example
+     * ```typescript
+     * 'use client';
+     *
+     * const router = useRouter();
+     * const pathname = usePathname();
+     * const searchParams = useSearchParams();
+     *
+     * useEffect(() => {
+     *     routingService.initialize(router, pathname, searchParams);
+     * }, [router, pathname, searchParams]);
+     * ```
+     */
+    initialize(router, pathname, searchParams) {
+        this.router = router;
+        this.pathname = pathname;
+        this.searchParams = searchParams;
+    }
+    // ===== URL Parameter Reading =====
+    getSearchParam(key) {
+        if (!this.searchParams) {
+            console.warn('NextAppRouterRoutingService not initialized. Call initialize() with Next.js hooks.');
+            return null;
+        }
+        return this.searchParams.get(key);
+    }
+    getAllSearchParams() {
+        if (!this.searchParams) {
+            console.warn('NextAppRouterRoutingService not initialized. Call initialize() with Next.js hooks.');
+            return new URLSearchParams();
+        }
+        return this.searchParams;
+    }
+    // ===== Navigation Operations =====
+    getCurrentPath() {
+        if (!this.pathname) {
+            console.warn('NextAppRouterRoutingService not initialized. Falling back to window.location.');
+            return window.location.pathname + window.location.search;
+        }
+        const search = this.searchParams?.toString();
+        return search ? `${this.pathname}?${search}` : this.pathname;
+    }
+    navigateTo(url) {
+        // External OAuth redirects (https://...) must use window.location
+        if (url.startsWith('http://') || url.startsWith('https://')) {
+            console.log('🌐 [NextJS] External OAuth redirect, using window.location:', url);
+            window.location.href = url;
+        }
+        else if (this.router) {
+            console.log('🔄 [NextJS] Internal navigation:', url);
+            this.router.push(url);
+        }
+        else {
+            console.warn('NextAppRouterRoutingService not initialized. Using window.location.');
+            window.location.href = url;
+        }
+    }
+    navigateReplace(path) {
+        if (this.router) {
+            console.log('🔄 [NextJS] Replacing URL:', path);
+            this.router.replace(path);
+        }
+        else {
+            console.warn('NextAppRouterRoutingService not initialized. Using window.history.');
+            window.history.replaceState({}, '', path);
+        }
+    }
+    openPopup(url, name, features) {
+        return window.open(url, name, features);
+    }
+}
+exports.NextAppRouterRoutingService = NextAppRouterRoutingService;

package/lib/services/PkceStorageService.d.ts

@@ -0,0 +1,55 @@
+import { IStorageService } from "./IStorageService";
+/**
+ * PKCE storage service (decorator pattern)
+ * Adds domain logic (key prefixes, validation) on top of generic storage
+ */
+export declare class PkceStorageService {
+    private storage;
+    private readonly prefix;
+    constructor(storage: IStorageService);
+    /**
+     * Store PKCE code verifier for a provider
+     * @param provider Provider name (microsoft, google, etc.)
+     * @param codeVerifier PKCE code verifier (43+ chars, Base64URL)
+     */
+    storeCodeVerifier(provider: string, codeVerifier: string): void;
+    /**
+     * Get PKCE code verifier for a provider
+     * @param provider Provider name
+     * @returns Code verifier or null if not found/invalid
+     */
+    getCodeVerifier(provider: string): string | null;
+    /**
+     * Get and remove PKCE code verifier (consume once)
+     * Used during token exchange to retrieve and cleanup
+     */
+    getAndRemoveCodeVerifier(provider: string): string | null;
+    /**
+     * Remove PKCE code verifier for a provider
+     */
+    removeCodeVerifier(provider: string): void;
+    /**
+     * Check if PKCE code verifier exists for a provider
+     */
+    hasCodeVerifier(provider: string): boolean;
+    /**
+     * Store PKCE code challenge for a provider (optional, for debugging)
+     */
+    storeCodeChallenge(provider: string, codeChallenge: string): void;
+    /**
+     * Get PKCE code challenge for a provider
+     */
+    getCodeChallenge(provider: string): string | null;
+    /**
+     * Remove PKCE code challenge for a provider
+     */
+    removeCodeChallenge(provider: string): void;
+    /**
+     * Clear all PKCE data for a provider
+     */
+    clearAll(provider: string): void;
+    /**
+     * Build storage key with prefix
+     */
+    private getKey;
+}

package/lib/services/PkceStorageService.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PkceStorageService = void 0;
+/**
+ * PKCE storage service (decorator pattern)
+ * Adds domain logic (key prefixes, validation) on top of generic storage
+ */
+class PkceStorageService {
+    storage;
+    prefix = 'rystem_pkce_';
+    constructor(storage) {
+        this.storage = storage;
+    }
+    /**
+     * Store PKCE code verifier for a provider
+     * @param provider Provider name (microsoft, google, etc.)
+     * @param codeVerifier PKCE code verifier (43+ chars, Base64URL)
+     */
+    storeCodeVerifier(provider, codeVerifier) {
+        if (!codeVerifier || codeVerifier.length < 43) {
+            console.warn(`PkceStorageService: Invalid code verifier for ${provider}`);
+            return;
+        }
+        const key = this.getKey(provider, 'verifier');
+        this.storage.set(key, codeVerifier);
+    }
+    /**
+     * Get PKCE code verifier for a provider
+     * @param provider Provider name
+     * @returns Code verifier or null if not found/invalid
+     */
+    getCodeVerifier(provider) {
+        const key = this.getKey(provider, 'verifier');
+        const value = this.storage.get(key);
+        // Validation: PKCE verifier must be at least 43 characters (RFC 7636)
+        if (value && value.length < 43) {
+            console.warn(`PkceStorageService: Invalid code verifier for ${provider} (length: ${value.length})`);
+            this.removeCodeVerifier(provider);
+            return null;
+        }
+        return value;
+    }
+    /**
+     * Get and remove PKCE code verifier (consume once)
+     * Used during token exchange to retrieve and cleanup
+     */
+    getAndRemoveCodeVerifier(provider) {
+        const verifier = this.getCodeVerifier(provider);
+        if (verifier) {
+            this.removeCodeVerifier(provider);
+        }
+        return verifier;
+    }
+    /**
+     * Remove PKCE code verifier for a provider
+     */
+    removeCodeVerifier(provider) {
+        const key = this.getKey(provider, 'verifier');
+        this.storage.remove(key);
+    }
+    /**
+     * Check if PKCE code verifier exists for a provider
+     */
+    hasCodeVerifier(provider) {
+        const key = this.getKey(provider, 'verifier');
+        return this.storage.has(key);
+    }
+    /**
+     * Store PKCE code challenge for a provider (optional, for debugging)
+     */
+    storeCodeChallenge(provider, codeChallenge) {
+        const key = this.getKey(provider, 'challenge');
+        this.storage.set(key, codeChallenge);
+    }
+    /**
+     * Get PKCE code challenge for a provider
+     */
+    getCodeChallenge(provider) {
+        const key = this.getKey(provider, 'challenge');
+        return this.storage.get(key);
+    }
+    /**
+     * Remove PKCE code challenge for a provider
+     */
+    removeCodeChallenge(provider) {
+        const key = this.getKey(provider, 'challenge');
+        this.storage.remove(key);
+    }
+    /**
+     * Clear all PKCE data for a provider
+     */
+    clearAll(provider) {
+        this.removeCodeVerifier(provider);
+        this.removeCodeChallenge(provider);
+    }
+    /**
+     * Build storage key with prefix
+     */
+    getKey(provider, type) {
+        return `${this.prefix}${provider}_${type}`;
+    }
+}
+exports.PkceStorageService = PkceStorageService;

package/lib/services/ReactRouterRoutingService.example.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Unified Routing Service for React Router v6+
+ *
+ * This service handles both URL parameter reading and navigation for React Router.
+ * Copy this file to your project and remove the `.example` extension.
+ *
+ * IMPORTANT: Must be initialized inside a React component with routing context.
+ *
+ * @example
+ * ```typescript
+ * import { ReactRouterRoutingService } from './ReactRouterRoutingService';
+ * import { useSearchParams, useNavigate, useLocation } from 'react-router-dom';
+ *
+ * const routingService = new ReactRouterRoutingService();
+ *
+ * setupSocialLogin(x => {
+ *     x.routingService = routingService;
+ * });
+ *
+ * function App() {
+ *     const [searchParams] = useSearchParams();
+ *     const navigate = useNavigate();
+ *     const location = useLocation();
+ *
+ *     useEffect(() => {
+ *         // Single initialization with all hooks
+ *         routingService.initialize(() => searchParams, navigate, location);
+ *     }, [searchParams, navigate, location]);
+ *
+ *     return <div>Your app</div>;
+ * }
+ * ```
+ */
+import type { IRoutingService } from './IRoutingService';
+/**
+ * Routing Service for React Router v6+
+ * Uses useSearchParams, useNavigate, and useLocation hooks
+ */
+export declare class ReactRouterRoutingService implements IRoutingService {
+    private searchParamsGetter;
+    private navigateFunc;
+    private location;
+    /**
+     * Initialize with React Router hooks
+     * MUST be called inside a React component with routing context
+     *
+     * @param searchParamsGetter - Function that returns URLSearchParams from useSearchParams()
+     * @param navigateFunc - The navigate function from useNavigate()
+     * @param location - The location object from useLocation()
+     *
+     * @example
+     * ```typescript
+     * const [searchParams] = useSearchParams();
+     * const navigate = useNavigate();
+     * const location = useLocation();
+     *
+     * useEffect(() => {
+     *     routingService.initialize(() => searchParams, navigate, location);
+     * }, [searchParams, navigate, location]);
+     * ```
+     */
+    initialize(searchParamsGetter: () => URLSearchParams, navigateFunc: (to: string, options?: any) => void, location: any): void;
+    getSearchParam(key: string): string | null;
+    getAllSearchParams(): URLSearchParams;
+    getCurrentPath(): string;
+    navigateTo(url: string): void;
+    navigateReplace(path: string): void;
+    openPopup(url: string, name: string, features: string): Window | null;
+}

package/lib/services/ReactRouterRoutingService.example.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * Unified Routing Service for React Router v6+
+ *
+ * This service handles both URL parameter reading and navigation for React Router.
+ * Copy this file to your project and remove the `.example` extension.
+ *
+ * IMPORTANT: Must be initialized inside a React component with routing context.
+ *
+ * @example
+ * ```typescript
+ * import { ReactRouterRoutingService } from './ReactRouterRoutingService';
+ * import { useSearchParams, useNavigate, useLocation } from 'react-router-dom';
+ *
+ * const routingService = new ReactRouterRoutingService();
+ *
+ * setupSocialLogin(x => {
+ *     x.routingService = routingService;
+ * });
+ *
+ * function App() {
+ *     const [searchParams] = useSearchParams();
+ *     const navigate = useNavigate();
+ *     const location = useLocation();
+ *
+ *     useEffect(() => {
+ *         // Single initialization with all hooks
+ *         routingService.initialize(() => searchParams, navigate, location);
+ *     }, [searchParams, navigate, location]);
+ *
+ *     return <div>Your app</div>;
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReactRouterRoutingService = void 0;
+/**
+ * Routing Service for React Router v6+
+ * Uses useSearchParams, useNavigate, and useLocation hooks
+ */
+class ReactRouterRoutingService {
+    searchParamsGetter = null;
+    navigateFunc = null;
+    location = null;
+    /**
+     * Initialize with React Router hooks
+     * MUST be called inside a React component with routing context
+     *
+     * @param searchParamsGetter - Function that returns URLSearchParams from useSearchParams()
+     * @param navigateFunc - The navigate function from useNavigate()
+     * @param location - The location object from useLocation()
+     *
+     * @example
+     * ```typescript
+     * const [searchParams] = useSearchParams();
+     * const navigate = useNavigate();
+     * const location = useLocation();
+     *
+     * useEffect(() => {
+     *     routingService.initialize(() => searchParams, navigate, location);
+     * }, [searchParams, navigate, location]);
+     * ```
+     */
+    initialize(searchParamsGetter, navigateFunc, location) {
+        this.searchParamsGetter = searchParamsGetter;
+        this.navigateFunc = navigateFunc;
+        this.location = location;
+    }
+    // ===== URL Parameter Reading =====
+    getSearchParam(key) {
+        if (!this.searchParamsGetter) {
+            console.warn('ReactRouterRoutingService not initialized. Call initialize() with React Router hooks.');
+            return null;
+        }
+        return this.searchParamsGetter().get(key);
+    }
+    getAllSearchParams() {
+        if (!this.searchParamsGetter) {
+            console.warn('ReactRouterRoutingService not initialized. Call initialize() with React Router hooks.');
+            return new URLSearchParams();
+        }
+        return this.searchParamsGetter();
+    }
+    // ===== Navigation Operations =====
+    getCurrentPath() {
+        if (!this.location) {
+            console.warn('ReactRouterRoutingService not initialized. Falling back to window.location.');
+            return window.location.pathname + window.location.search;
+        }
+        return this.location.pathname + this.location.search;
+    }
+    navigateTo(url) {
+        // External OAuth redirects (https://...) must use window.location
+        if (url.startsWith('http://') || url.startsWith('https://')) {
+            console.log('🌐 [ReactRouter] External OAuth redirect, using window.location:', url);
+            window.location.href = url;
+        }
+        else if (this.navigateFunc) {
+            console.log('🔄 [ReactRouter] Internal navigation:', url);
+            this.navigateFunc(url);
+        }
+        else {
+            console.warn('ReactRouterRoutingService not initialized. Using window.location.');
+            window.location.href = url;
+        }
+    }
+    navigateReplace(path) {
+        if (this.navigateFunc) {
+            console.log('🔄 [ReactRouter] Replacing URL:', path);
+            this.navigateFunc(path, { replace: true });
+        }
+        else {
+            console.warn('ReactRouterRoutingService not initialized. Using window.history.');
+            window.history.replaceState({}, '', path);
+        }
+    }
+    openPopup(url, name, features) {
+        return window.open(url, name, features);
+    }
+}
+exports.ReactRouterRoutingService = ReactRouterRoutingService;

package/lib/services/TokenStorageService.d.ts

@@ -0,0 +1,34 @@
+import { IStorageService } from "./IStorageService";
+import { Token } from "../models/Token";
+/**
+ * Token storage service (decorator pattern)
+ * Adds domain logic (expiry check, JSON serialization) on top of generic storage
+ */
+export declare class TokenStorageService {
+    private storage;
+    private readonly tokenKey;
+    private readonly expiryKey;
+    constructor(storage: IStorageService);
+    /**
+     * Save social authentication token
+     * @param token Token with expiry information (Date)
+     */
+    saveToken(token: Token): void;
+    /**
+     * Get social authentication token
+     * Returns null if not found or expired
+     */
+    getToken(): Token | null;
+    /**
+     * Check if token exists (not expired)
+     */
+    hasToken(): boolean;
+    /**
+     * Clear token from storage
+     */
+    clearToken(): void;
+    /**
+     * Check if token is expired
+     */
+    private isExpired;
+}

package/lib/services/TokenStorageService.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenStorageService = void 0;
+/**
+ * Token storage service (decorator pattern)
+ * Adds domain logic (expiry check, JSON serialization) on top of generic storage
+ */
+class TokenStorageService {
+    storage;
+    tokenKey = 'socialUserToken'; // Backward compatible key
+    expiryKey = 'socialUserToken_expiry';
+    constructor(storage) {
+        this.storage = storage;
+    }
+    /**
+     * Save social authentication token
+     * @param token Token with expiry information (Date)
+     */
+    saveToken(token) {
+        try {
+            this.storage.set(this.tokenKey, JSON.stringify(token));
+            // Store expiry separately for quick validation
+            if (token.expiresIn) {
+                this.storage.set(this.expiryKey, token.expiresIn.toISOString());
+            }
+        }
+        catch (error) {
+            console.error('TokenStorageService: Error saving token', error);
+        }
+    }
+    /**
+     * Get social authentication token
+     * Returns null if not found or expired
+     */
+    getToken() {
+        try {
+            // Check expiry first (faster than parsing JSON)
+            if (this.isExpired()) {
+                this.clearToken();
+                return null;
+            }
+            const raw = this.storage.get(this.tokenKey);
+            if (!raw) {
+                return null;
+            }
+            const token = JSON.parse(raw);
+            // Convert ISO string back to Date
+            if (token.expiresIn) {
+                token.expiresIn = new Date(token.expiresIn);
+            }
+            return token;
+        }
+        catch (error) {
+            console.error('TokenStorageService: Error getting token', error);
+            this.clearToken();
+            return null;
+        }
+    }
+    /**
+     * Check if token exists (not expired)
+     */
+    hasToken() {
+        return !this.isExpired() && this.storage.has(this.tokenKey);
+    }
+    /**
+     * Clear token from storage
+     */
+    clearToken() {
+        this.storage.remove(this.tokenKey);
+        this.storage.remove(this.expiryKey);
+    }
+    /**
+     * Check if token is expired
+     */
+    isExpired() {
+        const expiryRaw = this.storage.get(this.expiryKey);
+        if (!expiryRaw) {
+            return false; // No expiry set = no token or never expires
+        }
+        try {
+            const expiryDate = new Date(expiryRaw);
+            return expiryDate <= new Date();
+        }
+        catch (error) {
+            console.error('TokenStorageService: Error checking expiry', error);
+            return true; // If can't parse, consider expired
+        }
+    }
+}
+exports.TokenStorageService = TokenStorageService;

package/lib/services/UserStorageService.d.ts

@@ -0,0 +1,29 @@
+import { IStorageService } from "./IStorageService";
+import { SocialUser } from "../models/SocialUser";
+/**
+ * User storage service (decorator pattern)
+ * Adds domain logic (JSON serialization, identity transformation) on top of generic storage
+ */
+export declare class UserStorageService {
+    private storage;
+    private readonly userKey;
+    constructor(storage: IStorageService);
+    /**
+     * Save social user information
+     * @param user Social user data
+     */
+    saveUser<T = {}>(user: SocialUser<T>): void;
+    /**
+     * Get social user information
+     * Returns null if not found
+     */
+    getUser<T = {}>(): SocialUser<T> | null;
+    /**
+     * Check if user exists
+     */
+    hasUser(): boolean;
+    /**
+     * Clear user from storage
+     */
+    clearUser(): void;
+}

package/lib/services/UserStorageService.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserStorageService = void 0;
+/**
+ * User storage service (decorator pattern)
+ * Adds domain logic (JSON serialization, identity transformation) on top of generic storage
+ */
+class UserStorageService {
+    storage;
+    userKey = 'socialUser'; // Backward compatible key
+    constructor(storage) {
+        this.storage = storage;
+    }
+    /**
+     * Save social user information
+     * @param user Social user data
+     */
+    saveUser(user) {
+        try {
+            this.storage.set(this.userKey, JSON.stringify(user));
+        }
+        catch (error) {
+            console.error('UserStorageService: Error saving user', error);
+        }
+    }
+    /**
+     * Get social user information
+     * Returns null if not found
+     */
+    getUser() {
+        try {
+            const raw = this.storage.get(this.userKey);
+            if (!raw) {
+                return null;
+            }
+            return JSON.parse(raw);
+        }
+        catch (error) {
+            console.error('UserStorageService: Error getting user', error);
+            return null;
+        }
+    }
+    /**
+     * Check if user exists
+     */
+    hasUser() {
+        return this.storage.has(this.userKey);
+    }
+    /**
+     * Clear user from storage
+     */
+    clearUser() {
+        this.storage.remove(this.userKey);
+    }
+}
+exports.UserStorageService = UserStorageService;