@ubaidbinwaris/linkedin-login 2.1.0

package/Readme.md

@@ -0,0 +1,156 @@
+# @ubaidbinwaris/linkedin - Enterprise Automation Service
+
+![Version](https://img.shields.io/npm/v/@ubaidbinwaris/linkedin?style=flat-square)
+![License](https://img.shields.io/npm/l/@ubaidbinwaris/linkedin?style=flat-square)
+![Node](https://img.shields.io/node/v/@ubaidbinwaris/linkedin?style=flat-square)
+
+A professional, deterministic backend service library for managing multiple LinkedIn accounts with strict concurrency control, session isolation, and enterprise-grade security.
+
+> **v1.1.7 Update**: Introduces "Smart Mobile Verification" with Visible Browser Fallback.
+
+## 🚀 Key Features
+
+*   **🛡️ Multi-User Concurrency**: Built-in `SessionLock` prevents race conditions. Impossible to double-login the same user.
+*   **🔒 Enterprise Security**:
+    *   Sessions stored as `SHA-256` hashed filenames (GDPR/Privacy friendly).
+    *   Data encrypted with `AES-256-CBC` before storage.
+*   **🧠 Smart Validation**:
+    *   Caches validation checks for 10 minutes to minimize ban risk from excessive reloading.
+    *   Automatically refreshes stale sessions.
+*   **📱 Mobile & Fallback Support**:
+    *   **Phase 1**: Detects "Open LinkedIn App" prompt and waits 2 minutes for user approval.
+    *   **Phase 2**: If mobile fails, automatically launches a **Visible Browser** for manual intervention.
+
+## 🏗️ Architecture
+
+The library follows a strict **Fail-Fast** or **Resolution** flow. It does not use "stealth" plugins, relying instead on standard browser behavior and human intervention protocols.
+
+```mermaid
+sequenceDiagram
+    participant API as API/Worker
+    participant Pkg as LinkedIn Package
+    participant Browser as Playwright
+    participant Store as Session Store
+
+    API->>Pkg: loginToLinkedIn(email, pass)
+    Pkg->>Pkg: Acquire Lock (SessionLock)
+    alt is Locked
+        Pkg-->>API: Throw BUSY Error
+    end
+
+    Pkg->>Browser: Launch (Headless)
+    Pkg->>Store: Load Context
+    
+    alt Session Valid & Recent
+        Pkg-->>API: Return Page (Skip Feed)
+    else Session Stale/Invalid
+        Pkg->>Browser: Goto Feed
+        
+        alt Login Required
+            Pkg->>Browser: Fill Credentials
+            Pkg->>Browser: Submit
+            
+            opt Checkpoint Detected
+                Pkg->>Browser: Check Mobile Prompt
+                alt Mobile Prompt Found
+                    Pkg->>Pkg: Wait 2 Mins for Feed URL
+                end
+                
+                alt Mobile Failed
+                    Pkg->>Browser: Close Headless
+                    Pkg->>Browser: Launch VISIBLE Browser
+                    Pkg->>Browser: Re-Fill Credentials
+                    Pkg->>Pkg: Wait for Manual Use
+                end
+            end
+        end
+        
+        Pkg->>Store: Save Session (Encrypted)
+        Pkg-->>API: Return Page
+    end
+```
+
+## 📦 Installation
+
+```bash
+npm install @ubaidbinwaris/linkedin
+```
+
+## 💻 Usage
+
+### 1. Basic Implementation
+The simplest way to use the package. Locks and session management are handled automatically.
+
+```javascript
+const { loginToLinkedIn } = require('@ubaidbinwaris/linkedin');
+
+(async () => {
+    try {
+        const { browser, page } = await loginToLinkedIn({
+            headless: true // Will auto-switch to false if fallback needed
+        }, {
+            username: 'alice@example.com',
+            password: 'secure_password'
+        });
+
+        console.log("✅ Logged in successfully!");
+        
+        // ... Perform scraping/automation tasks ...
+
+        await browser.close();
+        
+    } catch (err) {
+        if (err.message === 'CHECKPOINT_DETECTED') {
+            console.error("❌ Critical: Account requires manual ID verification.");
+        } else if (err.message.includes('BUSY')) {
+            console.error("⚠️  User is already running a task.");
+        } else {
+            console.error("Error:", err.message);
+        }
+    }
+})();
+```
+
+### 2. Custom Storage (Database Integration)
+By default, sessions are saved to `./sessions`. Override this to use Redis, MongoDB, or PostgreSQL.
+
+```javascript
+const { setSessionStorage } = require('@ubaidbinwaris/linkedin');
+
+setSessionStorage({
+    read: async (email) => {
+        // Return encrypted JSON string from your DB
+        const result = await db.query('SELECT session_data FROM users WHERE email = $1', [email]);
+        return result.rows[0]?.session_data; 
+    },
+    write: async (email, data) => {
+        // Save encrypted JSON string to your DB
+        await db.query('UPDATE users SET session_data = $1 WHERE email = $2', [data, email]);
+    }
+});
+```
+
+### 3. Custom Logger
+Pipe internal logs to your own system (e.g., Winston, UI Stream).
+
+```javascript
+const { setLogger } = require('@ubaidbinwaris/linkedin');
+
+setLogger({
+    info: (msg) => console.log(`[LI-INFO] ${msg}`),
+    warn: (msg) => console.warn(`[LI-WARN] ${msg}`),
+    error: (msg) => console.error(`[LI-ERR] ${msg}`)
+});
+```
+
+## 🚨 Error Reference
+
+| Error Message | Meaning | Handling Action |
+| :--- | :--- | :--- |
+| `CHECKPOINT_DETECTED` | Security challenge (ID upload/Captcha) could not be resolved. | Notify admin. Manual Login required. |
+| `CHECKPOINT_DETECTED_M` | Manual Fallback (Visible Browser) timed out. | User didn't interact in time. Retry. |
+| `BUSY: ...` | A task is already running for this email. | Queue the request or reject it. |
+| `LOGIN_FAILED` | Credentials accepted, but session could not be verified. | Check proxy/network. |
+
+## License
+ISC

package/index.js

@@ -0,0 +1,13 @@
+// Main entry point
+const loginToLinkedIn = require('./src/login/login');
+const { setSessionDir, setSessionStorage } = require('./src/session/sessionManager');
+const { setLogger } = require('./src/utils/logger');
+const config = require('./src/config');
+
+module.exports = {
+    loginToLinkedIn,
+    setSessionDir,
+    setSessionStorage,
+    setLogger,
+    config
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@ubaidbinwaris/linkedin-login",
+  "version": "2.1.0",
+  "description": "",
+  "main": "index.js",
+  "files": [
+    "src",
+    "index.js",
+    "cli.js",
+    "Readme.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "node cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/UbaidBinWaris/linkedin.git"
+  },
+  "keywords": [
+    "linkedin",
+    "automation",
+    "bot",
+    "playwright"
+  ],
+  "author": "UbaidBinWaris",
+  "license": "MIT",
+  "type": "commonjs",
+  "bugs": {
+    "url": "https://github.com/UbaidBinWaris/linkedin/issues"
+  },
+  "homepage": "https://github.com/UbaidBinWaris/linkedin#readme",
+  "dependencies": {
+    "dotenv": "^17.2.4",
+    "playwright": "^1.58.2",
+    "winston": "^3.19.0"
+  }
+}

package/src/auth/actions.js

@@ -0,0 +1,52 @@
+const logger = require("../utils/logger");
+const { randomDelay } = require("../utils/time");
+
+const LINKEDIN_LOGIN = "https://www.linkedin.com/login";
+
+/**
+ * Performs credential-based login.
+ */
+async function performCredentialLogin(page, email, password) {
+  logger.info("Proceeding to credential login...");
+
+  if (!page.url().includes("login") && !page.url().includes("uas/request-password-reset")) {
+     await page.goto(LINKEDIN_LOGIN, { waitUntil: 'domcontentloaded' });
+     await randomDelay(1000, 2000);
+  }
+
+  logger.info("Entering credentials...");
+  
+  await page.click('input[name="session_key"]');
+  await randomDelay(500, 1000);
+  await page.type('input[name="session_key"]', email, { delay: 100 });
+  
+  await randomDelay(1000, 2000);
+  
+  await page.click('input[name="session_password"]');
+  await page.type('input[name="session_password"]', password, { delay: 100 });
+  
+  await randomDelay(1000, 2000);
+
+  logger.info("Submitting login form...");
+  await Promise.all([
+    page.waitForNavigation({ waitUntil: 'domcontentloaded' }),
+    page.click('button[type="submit"]')
+  ]);
+}
+
+const { VALIDATION_SELECTORS } = require("../config");
+
+/**
+ * Checks if the user is currently logged in (on feed).
+ */
+async function isLoggedIn(page) {
+  try {
+    const selector = VALIDATION_SELECTORS.join(", ");
+    await page.waitForSelector(selector, { timeout: 10000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { performCredentialLogin, isLoggedIn };

package/src/auth/checkpoint.js

@@ -0,0 +1,85 @@
+const logger = require("../utils/logger");
+
+/**
+ * Detects if a checkpoint/verification is triggered.
+ * Returns true if intervention is needed.
+ */
+async function detectCheckpoint(page) {
+  try {
+    const url = page.url();
+    if (
+      url.includes("checkpoint") ||
+      url.includes("challenge") ||
+      url.includes("verification") ||
+      url.includes("consumer-login/error")
+    ) {
+      return true;
+    }
+
+    try {
+      await page.waitForSelector("h1:has-text('Security Verification')", { timeout: 1000 });
+      return true;
+    } catch (e) {
+      // Element not found
+    }
+
+    return false;
+  } catch (error) {
+    logger.error(`Error during checkpoint detection: ${error.message}`);
+    return false;
+  }
+}
+
+/**
+ * Handles mobile verification/app approval prompts.
+ * Polls for success (feed navigation) for a set duration.
+ * @param {Page} page
+ * @returns {Promise<boolean>} true if resolved, false if timed out/failed
+ */
+async function handleMobileVerification(page) {
+    try {
+        const isMobileVerif = await page.evaluate(() => {
+            const text = document.body.innerText;
+            // User checks: "Check your LinkedIn app", "Open your LinkedIn app", "Approve the sign-in"
+            return text.includes("Check your LinkedIn app") || 
+                   text.includes("Open your LinkedIn app") ||
+                   text.includes("Tap Yes on the prompt") ||
+                   text.includes("verification request to your device") ||
+                   text.includes("Approve the sign-in");
+        });
+
+        if (!isMobileVerif) return false;
+
+        logger.warn("ACTION REQUIRED: Check your LinkedIn app on your phone! Waiting 2 minutes...");
+        
+        try {
+            // Poll for feed URL for 120 seconds
+            // Note: If navigation happens (user approves), this might throw "Execution context was destroyed"
+            // We handle that in the catch block by checking the URL.
+            await page.waitForFunction(() => {
+                return window.location.href.includes("/feed") || 
+                       document.querySelector('.global-nav__search');
+            }, { timeout: 120000 });
+
+            logger.info("Mobile verification successful! Resuming...");
+            return true; // Resolved
+        } catch (err) {
+            // Check if we actually succeeded via navigation
+            try {
+                if (page.url().includes("/feed")) {
+                    logger.info("Mobile verification successful (detected via navigation)! Resuming...");
+                    return true;
+                }
+            } catch(e) {}
+
+            logger.warn(`Mobile verification wait ended: ${err.message}`);
+            return false;
+        }
+
+    } catch (e) {
+         logger.warn(`Mobile verification check failed: ${e.message}`);
+         return false;
+    }
+}
+
+module.exports = { detectCheckpoint, handleMobileVerification };

package/src/browser/launcher.js

@@ -0,0 +1,62 @@
+const { chromium } = require("playwright");
+const logger = require("../utils/logger");
+const { loadSession } = require("../session/sessionManager");
+
+/**
+ * Creates and launches a browser instance.
+ * @param {Object} options - Launch options
+ */
+async function createBrowser(options = {}) {
+  const launchOptions = {
+    headless: options.headless !== undefined ? options.headless : true,
+    args: [
+      "--no-sandbox", 
+      "--disable-setuid-sandbox",
+    ],
+    ...options
+  };
+
+  logger.info("Launching browser (Standard Playwright)...");
+  return await chromium.launch(launchOptions);
+}
+
+/**
+ * Creates or loads a browser context.
+ * @param {import('playwright').Browser} browser
+ * @param {string} email - for session loading
+ */
+async function createContext(browser, email) {
+  const contextOptions = {
+    userAgent: getRandomUserAgent(),
+    viewport: getRandomViewport(),
+    locale: 'en-US',
+    timezoneId: 'America/New_York',
+    permissions: ['geolocation'],
+    ignoreHTTPSErrors: true,
+  };
+
+  logger.info(`Checking for saved session for ${email}...`);
+  const storedContext = await loadSession(browser, contextOptions, email);
+
+  if (storedContext) {
+    logger.info("Session stored context loaded.");
+    return storedContext;
+  }
+
+  logger.info("No valid session found. Creating new context.");
+  return await browser.newContext(contextOptions);
+}
+
+function getRandomViewport() {
+  const width = 1280 + Math.floor(Math.random() * 640);
+  const height = 720 + Math.floor(Math.random() * 360);
+  return { width, height };
+}
+
+function getRandomUserAgent() {
+  const versions = ["120.0.0.0", "121.0.0.0", "122.0.0.0"];
+  const version = versions[Math.floor(Math.random() * versions.length)];
+  return `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${version} Safari/537.36`;
+}
+
+module.exports = { createBrowser, createContext };

package/src/config.js

@@ -0,0 +1,14 @@
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+
+module.exports = {
+  // Session expiry time: 30 days
+  SESSION_MAX_AGE: 90 * ONE_DAY_MS, 
+
+  // Selectors to verify if the session is valid (logged in)
+  VALIDATION_SELECTORS: [
+    '.global-nav__search',
+    'input[placeholder="Search"]',
+    '#global-nav-typeahead',
+    '.feed-shared-update-v2' // Feed post container
+  ]
+};

package/src/login/login.js

@@ -0,0 +1,155 @@
+const logger = require("../utils/logger");
+const { saveSession, SessionLock } = require("../session/sessionManager");
+const { createBrowser, createContext } = require("../browser/launcher");
+const { detectCheckpoint, handleMobileVerification } = require("../auth/checkpoint");
+const { performCredentialLogin, isLoggedIn } = require("../auth/actions");
+const { randomDelay } = require("../utils/time");
+
+const LINKEDIN_FEED = "https://www.linkedin.com/feed/";
+
+/**
+ * Deterministic Login Flow wrapped in SessionLock
+ * 1. Acquire Lock (queues if busy)
+ * 2. Launch Browser
+ * 3. Load Session -> Check needsValidation
+ * 4. Login/Verify
+ * 5. Save Session (with timestamp)
+ */
+async function loginToLinkedIn(options = {}, credentials = null) {
+  const email = credentials?.username || process.env.LINKEDIN_EMAIL;
+  const password = credentials?.password || process.env.LINKEDIN_PASSWORD;
+
+  if (!email || !password) {
+    throw new Error("Missing LinkedIn credentials.");
+  }
+
+  // Wrap entire process in lock
+  return SessionLock.withLoginLock(email, async () => {
+      const browser = await createBrowser(options);
+      
+      try {
+        // ----------------------------
+        // STEP 1: Load Session & Context
+        // ----------------------------
+        const context = await createContext(browser, email);
+        const page = await context.newPage();
+        page.setDefaultTimeout(30000); 
+
+        // Check validation cache
+        // needsValidation is attached to context in sectionManager
+        if (context.needsValidation === false) {
+             logger.info(`[${email}] Session validation cached. Skipping feed check.`);
+             await page.goto(LINKEDIN_FEED, { waitUntil: "domcontentloaded" });
+             return { browser, context, page };
+        }
+
+        // ----------------------------
+        // STEP 2: Verify Session (if needed)
+        // ----------------------------
+        logger.info(`[${email}] Verifying session...`);
+        await page.goto(LINKEDIN_FEED, { waitUntil: "domcontentloaded" });
+        await randomDelay(1000, 2000);
+
+        if (await isLoggedIn(page)) {
+          logger.info(`[${email}] Session valid ✅`);
+          // Update validation timestamp
+          await saveSession(context, email, true);
+          return { browser, context, page };
+        }
+
+        logger.info(`[${email}] Session invalid. Clearing cookies and attempting credential login...`);
+        
+        // Clear old/corrupt cookies to ensure fresh login
+        await context.clearCookies();
+        
+        // ----------------------------
+        // STEP 3: Credential Login
+        // ----------------------------
+        await performCredentialLogin(page, email, password);
+
+        // ----------------------------
+        // STEP 4: Verify & Fail Fast
+        // ----------------------------
+        if (await detectCheckpoint(page)) {
+           // Attempt to handle mobile verification (2 min wait)
+           // If it returns true, it means we are now on the feed (resolved)
+           if (await handleMobileVerification(page)) {
+               // success, assume logged in
+               // Wait a moment for page to settle
+               await page.waitForTimeout(3000);
+               
+               // Double check if we are really on feed
+               if (page.url().includes("/feed") || await isLoggedIn(page)) {
+                    logger.info(`[${email}] Mobile Verification Successful ✅`);
+                    await saveSession(context, email, true);
+                    return { browser, context, page };
+               }
+           } else {
+               // Failed mobile verification. 
+               // User Request: "otherwise after some delay using browser opens the browser and fill the form"
+               
+               if (options.headless) {
+                   logger.info("[Fallback] Mobile verification failed. Switching to VISIBLE browser for manual intervention...");
+                   await browser.close();
+
+                   // RE-LAUNCH in Visible Mode
+                   const visibleBrowser = await createBrowser({ ...options, headless: false });
+                   const visibleContext = await createContext(visibleBrowser, email);
+                   const visiblePage = await visibleContext.newPage();
+                   visiblePage.setDefaultTimeout(60000); // More time for manual interaction
+
+                   try {
+                       logger.info("[Fallback] Filling credentials in visible browser...");
+                       await performCredentialLogin(visiblePage, email, password);
+                       
+                       // Now wait for success (Feed)
+                       logger.info("[Fallback] Waiting for user to complete login manually...");
+                       
+                       // Wait for URL OR Selector
+                       // We loop to check both condition
+                       try {
+                           await visiblePage.waitForFunction(() => {
+                               return window.location.href.includes("/feed") || 
+                                      document.querySelector(".global-nav__search");
+                           }, { timeout: 120000 });
+                       } catch(e) {
+                           logger.warn(`[Fallback] Wait finished with error: ${e.message}`);
+                       }
+                       
+                       // Double check status
+                       if (visiblePage.url().includes("/feed") || await isLoggedIn(visiblePage)) {
+                            logger.info(`[${email}] Manual Fallback Successful ✅`);
+                            await saveSession(visibleContext, email, true);
+                            return { browser: visibleBrowser, context: visibleContext, page: visiblePage };
+                       }
+                   } catch (fallbackErr) {
+                       logger.error(`[Fallback] Manual intervention failed or timed out: ${fallbackErr.message}`);
+                       await visibleBrowser.close();
+                       throw new Error("CHECKPOINT_DETECTED_M"); // M for manual failed
+                   }
+               }
+
+               const screenshotPath = `checkpoint_${email}_${Date.now()}.png`;
+               await page.screenshot({ path: screenshotPath });
+               logger.warn(`[${email}] Checkpoint detected! Screenshot saved: ${screenshotPath}`);
+               throw new Error("CHECKPOINT_DETECTED");
+           }
+        }
+
+        if (await isLoggedIn(page)) {
+           logger.info(`[${email}] Login successful ✅`);
+           await saveSession(context, email, true); // Save with validation = true
+           return { browser, context, page };
+        } else {
+           throw new Error("LOGIN_FAILED: Could not verify session after login attempt.");
+        }
+
+      } catch (error) {
+        logger.error(`[${email}] Login process failed: ${error.message}`);
+        await browser.close();
+        throw error;
+      }
+  });
+}
+
+module.exports = loginToLinkedIn;

package/src/session/SessionLock.js

@@ -0,0 +1,52 @@
+const logger = require("../utils/logger");
+
+/**
+ * In-memory lock map to prevent simultaneous login attempts for the same user.
+ * Map<email, Promise<any>>
+ */
+const activeLogins = new Map();
+
+const SessionLock = {
+  /**
+   * Executes a function with an exclusive lock for the given email.
+   * If a lock exists, it waits for it to release (or chains onto it? 
+   * Actually user requested: "if activeLogins.has(email) { return activeLogins.get(email); }"
+   * This means if a login is in progress, return that SAME promise. Join the existing attempt.)
+   * 
+   * @param {string} email 
+   * @param {Function} fn - Async function to execute
+   * @returns {Promise<any>}
+   */
+  async withLoginLock(email, fn) {
+    if (activeLogins.has(email)) {
+      logger.info(`[SessionLock] ${email} is already logging in. Joining existing request...`);
+      return activeLogins.get(email);
+    }
+
+    logger.info(`[SessionLock] Acquiring lock for ${email}...`);
+    
+    // Create a promise that wraps the execution
+    const promise = (async () => {
+      try {
+        return await fn();
+      } finally {
+        activeLogins.delete(email);
+        logger.info(`[SessionLock] Releasing lock for ${email}.`);
+      }
+    })();
+
+    activeLogins.set(email, promise);
+    return promise;
+  },
+
+  /**
+   * Checks if a user is currently locked.
+   * @param {string} email
+   * @returns {boolean}
+   */
+  isLocked(email) {
+    return activeLogins.has(email);
+  }
+};
+
+module.exports = SessionLock;

package/src/session/sessionManager.js

@@ -0,0 +1,208 @@
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const logger = require("../utils/logger");
+const SessionLock = require("./SessionLock"); // Keeping specific import, though widely used via login
+
+let sessionDir = path.join(process.cwd(), "data", "linkedin");
+
+/**
+ * Sets the directory where session files are stored.
+ * @param {string} dirPath - Absolute path to the session directory.
+ */
+function setSessionDir(dirPath) {
+  sessionDir = dirPath;
+}
+
+const ALGORITHM = "aes-256-cbc";
+const SECRET_KEY = process.env.SESSION_SECRET || "default_insecure_secret_key_32_bytes_long!!";
+const key = crypto.createHash("sha256").update(String(SECRET_KEY)).digest();
+
+function encrypt(text) {
+  const iv = crypto.randomBytes(16);
+  const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
+  let encrypted = cipher.update(text, 'utf8', 'hex');
+  encrypted += cipher.final('hex');
+  return iv.toString('hex') + ':' + encrypted;
+}
+
+function decrypt(text) {
+  try {
+    const textParts = text.split(':');
+    const iv = Buffer.from(textParts.shift(), 'hex');
+    const encryptedText = textParts.join(':');
+    const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
+    let decrypted = decipher.update(encryptedText, 'hex', 'utf8');
+    decrypted += decipher.final('utf8');
+    return decrypted;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Generates a SHA-256 hash of the email to use as filename.
+ * Privacy + filesystem safety.
+ * @param {string} email 
+ * @returns {string} hex hash
+ */
+function getSessionHash(email) {
+  if (!email) return "default";
+  return crypto.createHash("sha256").update(email).digest("hex");
+}
+
+function getSessionPath(email) {
+  const filename = `${getSessionHash(email)}.json`;
+  return path.join(sessionDir, filename);
+}
+
+function sessionExists(email) {
+  return fs.existsSync(getSessionPath(email));
+}
+
+const { SESSION_MAX_AGE } = require("../config"); // Assuming this exists, typically 7 days?
+
+// Validation Cache Duration (10 minutes)
+const VALIDATION_CACHE_MS = 10 * 60 * 1000;
+
+const defaultStorage = {
+  async read(email) {
+    const filePath = getSessionPath(email);
+    if (!fs.existsSync(filePath)) return null;
+    return fs.readFileSync(filePath, "utf-8");
+  },
+  
+  async write(email, data) {
+    const filePath = getSessionPath(email);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, data, "utf-8");
+  }
+};
+
+let currentStorage = defaultStorage;
+
+function setSessionStorage(adapter) {
+  if (adapter && typeof adapter.read === 'function' && typeof adapter.write === 'function') {
+    currentStorage = adapter;
+  } else {
+    logger.warn("Invalid storage adapter provided. Using default file storage.");
+  }
+}
+
+/**
+ * Saves the browser context state.
+ * @param {import('playwright').BrowserContext} context 
+ * @param {string} email 
+ * @param {boolean} [isValidated] - If true, updates lastValidatedAt
+ */
+async function saveSession(context, email, isValidated = false) {
+  try {
+    const state = await context.storageState();
+    
+    // Load existing metadata if possible to preserve creation time? 
+    // For now, simpler to just overwrite, but we might lose 'createdAt' if we had it.
+    // Let's just write new.
+    
+    const sessionData = {
+      timestamp: Date.now(), // Last saved
+      lastValidatedAt: isValidated ? Date.now() : undefined,
+      state: state
+      // Future: proxy binding here
+    };
+
+    const jsonString = JSON.stringify(sessionData);
+    const encryptedData = encrypt(jsonString);
+    
+    await currentStorage.write(email || "default", encryptedData);
+
+    logger.info(`Session saved for ${email} (Validated: ${isValidated}) 🔒`);
+  } catch (error) {
+    logger.error(`Failed to save session: ${error.message}`);
+  }
+}
+
+/**
+ * Loads the session.
+ * @returns {Promise<{ context: import('playwright').BrowserContext, needsValidation: boolean }>}
+ */
+async function loadSession(browser, options = {}, email) {
+  const user = email || "default";
+
+  try {
+    const fileContent = await currentStorage.read(user);
+    
+    if (!fileContent) {
+      logger.info(`No session found for ${user}.`);
+      return null;
+    }
+
+    let sessionData = null;
+    let state = null;
+
+    // Decrypt
+    const decrypted = decrypt(fileContent);
+    if (decrypted) {
+      try {
+        sessionData = JSON.parse(decrypted);
+      } catch (e) {
+        logger.error("Failed to parse session JSON.");
+        return null;
+      }
+    } else {
+        // Fallback for legacy plain JSON? 
+        try {
+            sessionData = JSON.parse(fileContent);
+        } catch(e) {}
+    }
+
+    if (!sessionData || !sessionData.state) {
+        logger.warn("Invalid or corrupt session data.");
+        return null;
+    }
+
+    // Check Age (Total expiry)
+    const age = Date.now() - sessionData.timestamp;
+    if (SESSION_MAX_AGE && age > SESSION_MAX_AGE) {
+         logger.warn(`Session expired (Age: ${age}ms).`);
+         return null;
+    }
+
+    state = sessionData.state;
+
+    // Check Validation Freshness
+    let needsValidation = true;
+    if (sessionData.lastValidatedAt) {
+        const valAge = Date.now() - sessionData.lastValidatedAt;
+        if (valAge < VALIDATION_CACHE_MS) {
+            needsValidation = false;
+            logger.info(`Session validation cached (Age: ${Math.round(valAge/1000)}s). Skipping checks.`);
+        }
+    }
+
+    const context = await browser.newContext({
+      storageState: state,
+      ...options
+    });
+    
+    // Attach metadata to context for caller to check? 
+    // Or return object? Returning object is a breaking change for internal API but we are in v2.
+    // Let's attach to context object directly as a property for convenience
+    context.needsValidation = needsValidation;
+    
+    return context;
+
+  } catch (error) {
+    logger.error(`Error loading session: ${error.message}`);
+    return null;
+  }
+}
+
+module.exports = {
+  setSessionDir,
+  setSessionStorage,
+  sessionExists,
+  getSessionPath,
+  saveSession,
+  loadSession,
+  SessionLock
+};

package/src/utils/logger.js

@@ -0,0 +1,51 @@
+const { createLogger, format, transports } = require("winston");
+const winston = require("winston");
+const path = require("path");
+const fs = require("fs");
+
+const logDir = path.join(__dirname, "../../logs");
+
+if (!fs.existsSync(logDir)) {
+  fs.mkdirSync(logDir, { recursive: true });
+}
+
+// Create default logger
+const defaultLogger = winston.createLogger({
+  level: "info",
+  format: winston.format.combine(
+    winston.format.timestamp({ format: "YYYY-MM-DD HH:mm:ss" }),
+    winston.format.printf(({ timestamp, level, message }) => {
+      return `${timestamp} [${level.toUpperCase()}]: ${message}`;
+    })
+  ),
+  transports: [
+    new winston.transports.File({ filename: path.join(logDir, "error.log"), level: "error" }),
+    new winston.transports.File({ filename: path.join(logDir, "combined.log") }),
+    new winston.transports.Console() // Output to console
+  ],
+});
+
+let currentLogger = defaultLogger;
+
+/**
+ * Sets a custom logger instance.
+ * @param {Object} customLogger - Logger object with info(), error(), warn(), debug() methods.
+ */
+function setLogger(customLogger) {
+  if (customLogger && typeof customLogger.info === 'function') {
+    currentLogger = customLogger;
+  } else {
+    console.warn("Invalid logger provided. Using default.");
+  }
+}
+
+// Proxy object to forward calls to the current logger
+const loggerProxy = {
+  info: (msg) => currentLogger.info(msg),
+  error: (msg) => currentLogger.error(msg),
+  warn: (msg) => currentLogger.warn(msg),
+  debug: (msg) => currentLogger.debug(msg),
+  setLogger // Export configuration method
+};
+
+module.exports = loggerProxy;

package/src/utils/terminal.js

@@ -0,0 +1,17 @@
+const readline = require("readline");
+
+function waitForUserResume(message = "Press ENTER to continue...") {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    rl.question(message, () => {
+      rl.close();
+      resolve();
+    });
+  });
+}
+
+module.exports = { waitForUserResume };

package/src/utils/time.js

@@ -0,0 +1,12 @@
+/**
+ * Returns a promise that resolves after a random delay between min and max milliseconds.
+ * @param {number} min - Minimum delay in ms.
+ * @param {number} max - Maximum delay in ms.
+ * @returns {Promise<void>}
+ */
+function randomDelay(min = 1000, max = 3000) {
+  const delay = Math.floor(Math.random() * (max - min + 1)) + min;
+  return new Promise((resolve) => setTimeout(resolve, delay));
+}
+
+module.exports = { randomDelay };