@mherod/get-cookie 4.3.2 → 4.4.0

package/eslint.config.js

@@ -64,13 +64,34 @@ export default [
         },
       ],
       "@typescript-eslint/no-floating-promises": "error",
-      "@typescript-eslint/no-misused-promises": "error",
+      "@typescript-eslint/no-misused-promises": [
+        "error",
+        {
+          checksVoidReturn: {
+            arguments: false,
+            attributes: false,
+            properties: false,
+            returns: true,
+            variables: true,
+          },
+          checksConditionals: true,
+        },
+      ],
       "@typescript-eslint/await-thenable": "error",
-      "@typescript-eslint/no-unnecessary-type-assertion": "error",
+      "@typescript-eslint/require-await": "error",
+      "@typescript-eslint/promise-function-async": "error",
+      "@typescript-eslint/prefer-promise-reject-errors": "error",
       "@typescript-eslint/prefer-nullish-coalescing": "error",
       "@typescript-eslint/prefer-optional-chain": "error",
       "@typescript-eslint/strict-boolean-expressions": "error",
       "@typescript-eslint/no-unnecessary-condition": "error",
+      "@typescript-eslint/no-unsafe-assignment": "error",
+      "@typescript-eslint/no-unsafe-return": "error",
+      "@typescript-eslint/no-unsafe-member-access": "error",
+      "@typescript-eslint/no-unsafe-call": "error",
+      "@typescript-eslint/no-unsafe-argument": "error",
+      "@typescript-eslint/no-unsafe-enum-comparison": "error",
+      "@typescript-eslint/prefer-readonly": "error",
       "import/order": [
         "error",
         {

package/examples/auth-tokens.ts

@@ -0,0 +1,143 @@
+#!/usr/bin/env tsx
+/**
+ * Example: Extracting authentication tokens from browser cookies
+ * This demonstrates how to use get-cookie for extracting auth tokens
+ * for API automation or testing purposes
+ */
+
+import { getCookie } from "../src";
+
+interface AuthToken {
+  site: string;
+  tokenName: string;
+  value: string;
+  browser: string;
+  expiry: Date | string | number | null;
+}
+
+async function extractAuthTokens() {
+  console.log("🔐 Authentication Token Extraction Example\n");
+  console.log("=".repeat(50));
+
+  // Common authentication cookie patterns
+  const authPatterns = [
+    {
+      site: "github.com",
+      cookies: ["user_session", "_gh_sess", "dotcom_user"],
+    },
+    {
+      site: "google.com",
+      cookies: ["OSID", "SID", "HSID", "SSID", "APISID", "SAPISID"],
+    },
+    { site: "twitter.com", cookies: ["auth_token", "ct0", "kdt"] },
+    { site: "linkedin.com", cookies: ["li_at", "JSESSIONID"] },
+    { site: "stackoverflow.com", cookies: ["acct", "prov"] },
+  ];
+
+  const foundTokens: AuthToken[] = [];
+
+  for (const pattern of authPatterns) {
+    console.log(`\n🔍 Checking ${pattern.site}...`);
+
+    for (const cookieName of pattern.cookies) {
+      try {
+        const cookies = await getCookie({
+          name: cookieName,
+          domain: pattern.site,
+        });
+
+        if (cookies.length > 0) {
+          cookies.forEach((cookie) => {
+            foundTokens.push({
+              site: pattern.site,
+              tokenName: cookieName,
+              value: `${cookie.value.substring(0, 20)}...`, // Truncate for security
+              browser: cookie.meta?.browser || "Unknown",
+              expiry: cookie.expiry || null,
+            });
+
+            console.log(
+              `  ✓ Found ${cookieName} in ${cookie.meta?.browser || "Unknown"}`,
+            );
+          });
+        }
+      } catch (_error) {
+        // Cookie not found or error accessing
+      }
+    }
+  }
+
+  // Summary
+  console.log(`\n${"=".repeat(50)}`);
+  console.log("📊 Summary of Found Authentication Tokens\n");
+
+  if (foundTokens.length === 0) {
+    console.log(
+      "No authentication tokens found. Make sure you're logged into these sites.",
+    );
+  } else {
+    // Group by site
+    const bySite = foundTokens.reduce(
+      (acc, token) => {
+        if (!acc[token.site]) {
+          acc[token.site] = [];
+        }
+        acc[token.site]?.push(token);
+        return acc;
+      },
+      {} as Record<string, AuthToken[]>,
+    );
+
+    Object.entries(bySite).forEach(([site, tokens]) => {
+      console.log(`\n${site}:`);
+      tokens.forEach((token) => {
+        const expiryInfo =
+          token.expiry instanceof Date
+            ? `expires ${new Date(token.expiry).toLocaleDateString()}`
+            : token.expiry === "Infinity"
+              ? "session cookie"
+              : "unknown expiry";
+
+        console.log(`  • ${token.tokenName} (${token.browser}, ${expiryInfo})`);
+        console.log(`    Value: ${token.value}`);
+      });
+    });
+
+    // Security reminder
+    console.log("\n⚠️  Security Reminder:");
+    console.log("These are sensitive authentication tokens. Never:");
+    console.log("  - Share them publicly");
+    console.log("  - Commit them to version control");
+    console.log("  - Use them outside of their intended purpose");
+  }
+
+  // Example: Using tokens for API requests
+  console.log(`\n${"=".repeat(50)}`);
+  console.log("💡 Example: Using GitHub token for API request\n");
+
+  const githubSession = foundTokens.find(
+    (t) => t.site === "github.com" && t.tokenName === "user_session",
+  );
+
+  if (githubSession) {
+    console.log("To use this token with GitHub API:");
+    console.log("```javascript");
+    console.log(
+      "const response = await fetch('https://api.github.com/user', {",
+    );
+    console.log("  headers: {");
+    console.log("    'Cookie': `user_session=\\$\\{token\\}`,");
+    console.log("    'User-Agent': 'Your-App-Name'");
+    console.log("  }");
+    console.log("});");
+    console.log("```");
+    console.log("\nNote: Most modern APIs prefer OAuth tokens over cookies.");
+  } else {
+    console.log(
+      "No GitHub session found. Log into GitHub in your browser first.",
+    );
+  }
+}
+
+// Run the example
+extractAuthTokens().catch(console.error);

package/examples/chrome-cookies-demo.sh

@@ -0,0 +1,117 @@
+#!/bin/bash
+
+# Chrome-specific cookie extraction demo
+echo "🍪 Chrome Cookie Extraction with get-cookie"
+echo "==========================================="
+echo ""
+
+# Basic Chrome cookie extraction
+echo "1️⃣ Basic Chrome cookie extraction:"
+echo "─────────────────────────────────"
+echo "Command: get-cookie --url https://github.com --browser chrome --render"
+echo ""
+COOKIES=$(get-cookie --url https://github.com --browser chrome --render 2>/dev/null | head -c 100)
+echo "Output (truncated): $COOKIES..."
+echo ""
+
+# JSON output for debugging
+echo "2️⃣ Chrome cookies in JSON format:"
+echo "────────────────────────────────"
+echo "Command: get-cookie --url https://github.com --browser chrome --output json"
+echo ""
+get-cookie --url https://github.com --browser chrome --output json 2>/dev/null | jq '.[:2]'
+echo ""
+
+# Filtering duplicates
+echo "3️⃣ Handling duplicate cookies:"
+echo "─────────────────────────────"
+echo "Chrome may have duplicate cookies from different profiles."
+echo ""
+echo "Session cookies found:"
+get-cookie --url https://github.com --browser chrome --output json 2>/dev/null | \
+    jq -r '.[] | select(.name == "user_session") | "  • \(.value[0:20])... (\(.value | length) chars)"'
+echo ""
+
+# Smart filtering
+echo "4️⃣ Smart cookie filtering (recommended):"
+echo "───────────────────────────────────────"
+echo "Filter to get the longest (most likely valid) cookie value:"
+echo ""
+cat << 'EOF'
+VALID_SESSION=$(get-cookie --url https://github.com --browser chrome --output json | \
+    jq -r '.[] | select(.name == "user_session" and (.value | length) > 20) | .value' | \
+    head -1)
+EOF
+echo ""
+
+# Using with curl
+echo "5️⃣ Using Chrome cookies with curl:"
+echo "────────────────────────────────"
+echo "Simple approach (may fail with duplicates):"
+echo 'curl -H "Cookie: $(get-cookie --url <URL> --browser chrome --render)" <URL>'
+echo ""
+echo "Robust approach (with filtering):"
+cat << 'EOF'
+# Get deduplicated cookies (longest value wins)
+COOKIES=$(get-cookie --url <URL> --browser chrome --output json | \
+    jq -r 'group_by(.name) | map(max_by(.value | length)) | 
+    .[] | "\(.name)=\(.value)"' | tr '\n' ';')
+
+curl -H "Cookie: $COOKIES" <URL>
+EOF
+echo ""
+
+# Testing authentication
+echo "6️⃣ Testing GitHub authentication with Chrome cookies:"
+echo "───────────────────────────────────────────────────"
+COOKIES=$(get-cookie --url https://github.com --browser chrome --output json 2>/dev/null | \
+    jq -r 'group_by(.name) | map(max_by(.value | length)) | .[] | "\(.name)=\(.value)"' | tr '\n' ';')
+
+echo -n "Testing with deduplicated cookies: "
+HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
+    -H "Cookie: $COOKIES" \
+    -H "User-Agent: Mozilla/5.0" \
+    "https://github.com/settings/profile")
+
+if [ "$HTTP_CODE" = "200" ]; then
+    echo "✅ Success (HTTP 200)"
+elif [ "$HTTP_CODE" = "302" ]; then
+    echo "❌ Redirected to login (HTTP 302)"
+else
+    echo "⚠️  HTTP $HTTP_CODE"
+fi
+echo ""
+
+# Check cookie counts
+echo "7️⃣ Cookie statistics:"
+echo "──────────────────"
+TOTAL=$(get-cookie --url https://github.com --browser chrome --output json 2>/dev/null | jq 'length')
+UNIQUE=$(get-cookie --url https://github.com --browser chrome --output json 2>/dev/null | jq '[.[] | .name] | unique | length')
+echo "• Total cookies: $TOTAL"
+echo "• Unique cookie names: $UNIQUE"
+echo "• Duplicates: $((TOTAL - UNIQUE))"
+echo ""
+
+# Expired cookie filtering
+echo "8️⃣ Expired cookie filtering:"
+echo "──────────────────────────"
+WITHOUT=$(get-cookie --url https://github.com --browser chrome --output json 2>/dev/null | jq 'length')
+WITH=$(get-cookie --url https://github.com --browser chrome --output json --include-expired 2>/dev/null | jq 'length')
+echo "• Without --include-expired: $WITHOUT cookies"
+echo "• With --include-expired: $WITH cookies"
+if [ "$WITH" -gt "$WITHOUT" ]; then
+    echo "• ✅ Filtered out $((WITH - WITHOUT)) expired cookies"
+else
+    echo "• ℹ️  No expired cookies found"
+fi
+echo ""
+
+echo "💡 Key Insights:"
+echo "──────────────"
+echo "• Chrome may store duplicate cookies from different profiles"
+echo "• The --render flag outputs all cookies, including duplicates"
+echo "• For authentication, deduplicate by taking the longest value"
+echo "• Expired cookies are filtered by default (use --include-expired to see all)"
+echo "• Use JSON output + jq for precise cookie control"
+echo ""
+echo "✅ Chrome cookie extraction complete!"

package/examples/chrome-profile-demo.sh

@@ -0,0 +1,126 @@
+#!/bin/bash
+
+# Chrome Profile Selection Demo
+echo "🍪 Chrome Profile Selection with get-cookie"
+echo "==========================================="
+echo ""
+echo "The new --profile option allows targeting specific Chrome profiles by name."
+echo ""
+
+# List available Chrome profiles
+echo "📋 Available Chrome Profiles:"
+echo "──────────────────────────"
+if [ -f ~/Library/Application\ Support/Google/Chrome/Local\ State ]; then
+    cat ~/Library/Application\ Support/Google/Chrome/Local\ State | \
+        jq -r '.profile.info_cache | to_entries | .[] | "  • \(.value.name) (directory: \(.key))"'
+else
+    echo "  Chrome Local State file not found"
+fi
+echo ""
+
+# Demonstrate profile-specific extraction
+echo "🎯 Profile-Specific Cookie Extraction:"
+echo "────────────────────────────────────"
+echo ""
+
+echo "1️⃣ Extract from a specific profile by name:"
+echo "   Command: get-cookie --url https://github.com --browser chrome --profile \"plugg.in\" --render"
+echo ""
+COOKIES=$(get-cookie --url https://github.com --browser chrome --profile "plugg.in" --render 2>/dev/null | head -c 80)
+echo "   Output: $COOKIES..."
+echo ""
+
+echo "2️⃣ Compare different profiles for the same cookie:"
+echo ""
+echo "   Default/Personal profile:"
+echo "   $ get-cookie user_session github.com --browser chrome --profile \"Personal\" --render"
+PERSONAL=$(get-cookie user_session github.com --browser chrome --profile "Personal" --render 2>/dev/null)
+if [ -n "$PERSONAL" ]; then
+    VALUE=$(echo "$PERSONAL" | cut -d'=' -f2)
+    echo "   Result: user_session=${VALUE:0:20}... (${#VALUE} chars)"
+else
+    echo "   Result: No user_session cookie found"
+fi
+echo ""
+
+echo "   Profile 9/plugg.in profile:"
+echo "   $ get-cookie user_session github.com --browser chrome --profile \"plugg.in\" --render"
+PLUGIN=$(get-cookie user_session github.com --browser chrome --profile "plugg.in" --render 2>/dev/null)
+if [ -n "$PLUGIN" ]; then
+    VALUE=$(echo "$PLUGIN" | cut -d'=' -f2)
+    echo "   Result: user_session=${VALUE:0:20}... (${#VALUE} chars)"
+else
+    echo "   Result: No user_session cookie found"
+fi
+echo ""
+
+# Show the benefit
+echo "💡 Benefits of Profile Selection:"
+echo "───────────────────────────────"
+echo "• Avoid cookie conflicts between profiles"
+echo "• Target the correct logged-in session"
+echo "• No need for deduplication when using specific profile"
+echo "• Faster queries (only searches one profile)"
+echo ""
+
+# Practical curl example
+echo "🔧 Practical Example with curl:"
+echo "─────────────────────────────"
+echo ""
+echo "Use the correct profile for authenticated requests:"
+echo ""
+cat << 'EOF'
+# Get cookies from your work profile
+COOKIES=$(get-cookie --url https://github.com --browser chrome --profile "Work" --render)
+curl -H "Cookie: $COOKIES" https://github.com/settings/profile
+
+# Get cookies from your personal profile  
+COOKIES=$(get-cookie --url https://github.com --browser chrome --profile "Personal" --render)
+curl -H "Cookie: $COOKIES" https://github.com/settings/profile
+EOF
+echo ""
+
+# Test with curl
+echo "🧪 Live Test with GitHub:"
+echo "──────────────────────"
+echo ""
+
+test_profile() {
+    local profile=$1
+    echo -n "Testing profile '$profile': "
+    
+    COOKIES=$(get-cookie --url https://github.com/settings/profile --browser chrome --profile "$profile" --render 2>/dev/null)
+    
+    if [ -z "$COOKIES" ]; then
+        echo "❌ No cookies found"
+        return
+    fi
+    
+    HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
+        -H "Cookie: $COOKIES" \
+        -H "User-Agent: Mozilla/5.0" \
+        "https://github.com/settings/profile")
+    
+    if [ "$HTTP_CODE" = "200" ]; then
+        echo "✅ Authenticated (HTTP 200)"
+    elif [ "$HTTP_CODE" = "302" ]; then
+        echo "🔄 Redirected to login (HTTP 302)"
+    else
+        echo "⚠️  HTTP $HTTP_CODE"
+    fi
+}
+
+# Test each profile that might have GitHub cookies
+test_profile "Personal"
+test_profile "plugg.in"
+echo ""
+
+echo "📝 Usage Notes:"
+echo "────────────"
+echo "• Profile names are case-insensitive"
+echo "• You can use either the display name (e.g., \"Personal\") or directory name (e.g., \"Default\")"
+echo "• If no --profile is specified, all profiles are queried"
+echo "• Combine with --include-all to see cookies from all profiles even when one is selected"
+echo ""
+
+echo "✅ Profile selection feature is working perfectly!"

package/examples/comprehensive-demo.ts

@@ -0,0 +1,202 @@
+#!/usr/bin/env tsx
+/**
+ * Comprehensive demonstration of get-cookie library features
+ * This example shows various ways to query and work with browser cookies
+ */
+
+import { getCookie } from "../src";
+import { CookieStrategyFactory } from "../src/cli/services/CookieStrategyFactory";
+
+async function demonstrateFeatures() {
+  console.log("🍪 Get-Cookie Library Demonstration\n");
+  console.log("=".repeat(50));
+
+  // 1. Basic cookie retrieval
+  console.log("\n📌 Example 1: Get specific cookies by name");
+  console.log("-".repeat(40));
+  try {
+    const githubSession = await getCookie({
+      name: "user_session",
+      domain: "github.com",
+    });
+
+    if (githubSession.length > 0) {
+      console.log(
+        `Found ${githubSession.length} GitHub user_session cookie(s):`,
+      );
+      githubSession.forEach((cookie, i) => {
+        console.log(
+          `  ${i + 1}. Browser: ${cookie.meta?.browser || "Unknown"}`,
+        );
+        console.log(
+          `     Profile: ${cookie.meta?.file?.split("/").slice(-2, -1)[0] || "Default"}`,
+        );
+        console.log(`     Expires: ${cookie.expiry}`);
+        console.log(`     Decrypted: ${cookie.meta?.decrypted || "N/A"}`);
+      });
+    } else {
+      console.log("No GitHub user_session cookies found");
+    }
+  } catch (error) {
+    console.error("Error retrieving cookies:", error);
+  }
+
+  // 2. Wildcard search
+  console.log("\n📌 Example 2: Wildcard search for all cookies");
+  console.log("-".repeat(40));
+  try {
+    const allGoogleCookies = await getCookie({
+      name: "%", // Wildcard for any name
+      domain: "google.com",
+    });
+
+    if (allGoogleCookies.length > 0) {
+      // Group by cookie name
+      const cookieNames = [...new Set(allGoogleCookies.map((c) => c.name))];
+      console.log(`Found ${allGoogleCookies.length} Google cookies:`);
+      console.log(`Unique cookie names (${cookieNames.length}):`);
+      cookieNames.slice(0, 10).forEach((name) => {
+        const count = allGoogleCookies.filter((c) => c.name === name).length;
+        console.log(`  - ${name} (${count} instance${count > 1 ? "s" : ""})`);
+      });
+      if (cookieNames.length > 10) {
+        console.log(`  ... and ${cookieNames.length - 10} more`);
+      }
+    } else {
+      console.log("No Google cookies found");
+    }
+  } catch (error) {
+    console.error("Error retrieving cookies:", error);
+  }
+
+  // 3. Browser-specific queries
+  console.log("\n📌 Example 3: Browser-specific strategies");
+  console.log("-".repeat(40));
+
+  const browsers = ["chrome", "firefox", "safari"];
+  for (const browser of browsers) {
+    try {
+      const strategy = CookieStrategyFactory.createStrategy(browser);
+      const cookies = await strategy.queryCookies("%", "github.com");
+
+      if (cookies.length > 0) {
+        console.log(
+          `✓ ${browser.toUpperCase()}: Found ${cookies.length} GitHub cookies`,
+        );
+      } else {
+        console.log(
+          `✗ ${browser.toUpperCase()}: No GitHub cookies or browser not available`,
+        );
+      }
+    } catch (_error) {
+      console.log(`✗ ${browser.toUpperCase()}: Not available on this system`);
+    }
+  }
+
+  // 4. Composite strategy (all browsers)
+  console.log("\n📌 Example 4: Composite strategy (query all browsers)");
+  console.log("-".repeat(40));
+  try {
+    const compositeStrategy = CookieStrategyFactory.createStrategy();
+    const allCookies = await compositeStrategy.queryCookies("%", "github.com");
+
+    // Group by browser
+    const browserGroups = allCookies.reduce(
+      (acc, cookie) => {
+        const browser = cookie.meta?.browser || "Unknown";
+        if (!acc[browser]) {
+          acc[browser] = [];
+        }
+        acc[browser].push(cookie);
+        return acc;
+      },
+      {} as Record<string, typeof allCookies>,
+    );
+
+    console.log("Cookies found across all browsers:");
+    Object.entries(browserGroups).forEach(([browser, cookies]) => {
+      const uniqueNames = [...new Set(cookies.map((c) => c.name))];
+      console.log(
+        `  ${browser}: ${cookies.length} cookies (${uniqueNames.length} unique names)`,
+      );
+    });
+  } catch (error) {
+    console.error("Error with composite strategy:", error);
+  }
+
+  // 5. Session vs Persistent cookies
+  console.log("\n📌 Example 5: Session vs Persistent cookies");
+  console.log("-".repeat(40));
+  try {
+    const allCookies = await getCookie({
+      name: "%",
+      domain: "google.com",
+    });
+
+    const sessionCookies = allCookies.filter(
+      (c) =>
+        c.expiry === "Infinity" || c.expiry === undefined || c.expiry === null,
+    );
+    const persistentCookies = allCookies.filter(
+      (c) => c.expiry && c.expiry !== "Infinity",
+    );
+
+    console.log(`Session cookies: ${sessionCookies.length}`);
+    console.log(`Persistent cookies: ${persistentCookies.length}`);
+
+    if (persistentCookies.length > 0) {
+      // Find the cookie expiring soonest
+      const cookiesWithDates = persistentCookies.filter(
+        (c): c is typeof c & { expiry: Date } => c.expiry instanceof Date,
+      );
+      const soonest = cookiesWithDates.sort((a, b) => {
+        const dateA = a.expiry.getTime();
+        const dateB = b.expiry.getTime();
+        return dateA - dateB;
+      })[0];
+
+      if (soonest) {
+        const daysUntilExpiry = Math.ceil(
+          (soonest.expiry.getTime() - Date.now()) / (1000 * 60 * 60 * 24),
+        );
+        console.log(
+          `Cookie expiring soonest: ${soonest.name} (${daysUntilExpiry} days)`,
+        );
+      }
+    }
+  } catch (error) {
+    console.error("Error analyzing cookies:", error);
+  }
+
+  // 6. Performance measurement
+  console.log("\n📌 Example 6: Performance measurement");
+  console.log("-".repeat(40));
+
+  const iterations = 5;
+  const times: number[] = [];
+
+  for (let i = 0; i < iterations; i++) {
+    const start = Date.now();
+    await getCookie({
+      name: "%",
+      domain: "github.com",
+    });
+    const elapsed = Date.now() - start;
+    times.push(elapsed);
+  }
+
+  const avgTime = times.reduce((a, b) => a + b, 0) / times.length;
+  const minTime = Math.min(...times);
+  const maxTime = Math.max(...times);
+
+  console.log(`Query performance (${iterations} iterations):`);
+  console.log(`  Average: ${avgTime.toFixed(2)}ms`);
+  console.log(`  Min: ${minTime}ms`);
+  console.log(`  Max: ${maxTime}ms`);
+
+  console.log(`\n${"=".repeat(50)}`);
+  console.log("✅ Demonstration complete!");
+}
+
+// Run the demonstration
+demonstrateFeatures().catch(console.error);