plx-converter 0.1.3 → 0.1.5

package/README.md

@@ -66,13 +66,24 @@ dozen-odd cookies, so copy the entire `cookie:` value: on [music.youtube.com](ht
 DevTools → **Network** → any request → **Request Headers** → `cookie:`. Google sessions also expire
 faster than the other two, so expect to redo this occasionally.
 
-### Auto-fetch from your browser (macOS)
+### Auto-fetch from your browser
 
-Rather than copying cookies by hand, plx can read them straight from a logged-in browser — you only
-accept the macOS Keychain prompt. Pick **"Auto-fetch credentials (from browser)"** from the menu, or
-let it run automatically when a credential is missing. Works with the Chromium family (Brave, Chrome,
-Edge, Chromium, Vivaldi, Opera) and Safari (needs Full Disk Access). Manual paste stays the fallback
-everywhere else.
+Rather than copying cookies by hand, plx can read them straight from a logged-in browser. Pick
+**"Auto-fetch credentials (from browser)"** from the menu, or let it run automatically when a
+credential is missing. Manual paste stays the fallback everywhere.
+
+| Browser | macOS | Windows | Linux |
+|---|---|---|---|
+| Firefox | ✅ | ✅ | ✅ |
+| Chromium family (Brave, Chrome, Edge, Chromium, Vivaldi, Opera) | ✅ | — | — |
+| Safari | ✅ — needs Full Disk Access | — | — |
+
+On macOS the Chromium and Safari backends ask you to accept the Keychain prompt once. Firefox needs
+no prompt on any OS, since it stores cookie values unencrypted.
+
+Chromium on Windows isn't a gap waiting to be filled: since Chrome 127 the cookie key is sealed
+behind App-Bound Encryption that only a SYSTEM-level process can unwrap, and every published
+workaround is the sort of thing malware does. On Windows, use Firefox or paste manually.
 
 Set credentials in `.env`, export them in your shell, or paste when prompted. Full setup:
 [`docs/CONFIG.md`](docs/CONFIG.md).

package/dist/browser.js

@@ -1,7 +1,7 @@
 import { createDecipheriv, pbkdf2Sync } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { homedir, platform } from 'node:os';
+import { copyFileSync, existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { homedir, platform, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { YTMUSIC_COOKIES, cookieHeader } from './ytmusic.js';
@@ -156,17 +156,77 @@ function readSafari() {
     }
     return {};
 }
+// Firefox — the one backend that is not macOS-only. `cookies.sqlite` stores values in **plaintext**:
+// no keychain, no DPAPI, and none of the App-Bound Encryption that closed the Chromium family off on
+// Windows (Chrome 127+ wraps the cookie key in SYSTEM-DPAPI, so only a SYSTEM process can unwrap it,
+// and every published bypass is malware behaviour). `key4.db` is commonly assumed to encrypt these
+// too — it does not; it protects saved *logins*.
+const FIREFOX_ROOTS = {
+    win32: join(process.env.APPDATA ?? join(homedir(), 'AppData', 'Roaming'), 'Mozilla', 'Firefox'),
+    darwin: join(homedir(), 'Library', 'Application Support', 'Firefox'),
+    linux: join(homedir(), '.mozilla', 'firefox'),
+};
+// Every profile holding a cookie DB, most-recently-written first. `profiles.ini` names the default
+// one, but reading it needs an INI parser to answer worse than an mtime sort already does: someone
+// with several profiles is logged in on the one they actually use, which is the one just written to.
+export function firefoxProfiles(root = FIREFOX_ROOTS[platform()] ?? FIREFOX_ROOTS.linux) {
+    const nested = join(root, 'Profiles');
+    const base = existsSync(nested) ? nested : root; // some Linux packagings drop the Profiles/ level
+    try {
+        return readdirSync(base, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => join(base, entry.name, 'cookies.sqlite'))
+            .filter(existsSync)
+            .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+    }
+    catch {
+        return []; // no Firefox installed, or an unreadable profile root
+    }
+}
+// Firefox keeps the DB in WAL mode and holds it open while running — on Windows that lock is
+// enforced, so reading the file in place fails outright. Copy it to a temp dir and read the copy.
+// The `-wal` sidecar comes along because a cookie set this session may not be checkpointed into the
+// main file yet, and the copy is opened writable precisely so SQLite is allowed to replay it.
+export function readFirefox(dbPath) {
+    let dir = null;
+    try {
+        dir = mkdtempSync(join(tmpdir(), 'plx-ff-'));
+        const copy = join(dir, 'cookies.sqlite');
+        copyFileSync(dbPath, copy);
+        if (existsSync(`${dbPath}-wal`))
+            copyFileSync(`${dbPath}-wal`, `${copy}-wal`);
+        const db = new DatabaseSync(copy);
+        try {
+            const query = `SELECT name, host, value FROM moz_cookies WHERE name IN (${COOKIE_NAMES.map(() => '?').join(',')})`;
+            // `host` is stored dot-prefixed for domain cookies (`.youtube.com`); hostRank's endsWith arm
+            // already accepts that, so it is passed through as-is.
+            return collect(db.prepare(query).all(...COOKIE_NAMES));
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch {
+        return {}; // unreadable profile / changed schema — skip it
+    }
+    finally {
+        if (dir)
+            rmSync(dir, { recursive: true, force: true });
+    }
+}
 // Auto-retrieve credentials from the first logged-in browser that has them, keyed by provider —
 // the parsers above speak in cookie names, and this is where that becomes one opaque string per
 // provider for the config layer to store. Never throws: a missing browser, locked DB, denied
 // keychain, or TCC block just yields {}. Manual paste stays the fallback.
 export function fetchBrowserCredentials() {
-    if (platform() !== 'darwin')
-        return {};
+    // The keychain-backed backends stay gated on macOS; Firefox runs everywhere and is all that
+    // Windows and Linux get. macOS keeps its original order, so nothing changes for anyone who
+    // already relied on this — Firefox only fills what the others left empty.
+    const keychainBacked = platform() === 'darwin' ? [...CHROMIUM_BROWSERS.map(readChromium), readSafari()] : [];
     const credentials = {};
     // Every backend is read rather than stopping at the first: a user may be logged into Deezer in one
     // browser and YouTube Music in another.
-    for (const found of [...CHROMIUM_BROWSERS.map(readChromium), readSafari()]) {
+    for (const found of [...keychainBacked, ...firefoxProfiles().map(readFirefox)]) {
         if (!credentials.deezer && found.arl)
             credentials.deezer = found.arl;
         if (!credentials.spotify && found.sp_dc)
@@ -183,3 +243,18 @@ export function fetchBrowserCredentials() {
     }
     return credentials;
 }
+// Why auto-fetch came back empty, said in the terms of the platform the user is actually on. macOS
+// is the only place a denied Keychain prompt can be the answer; everywhere else Firefox is the only
+// backend, so the useful thing to report is which half of that is missing. This says *why* only —
+// the caller owns pointing at the manual paste, so that instruction lives in one place. Both inputs
+// are injected so the branches are testable without a browser or a second OS.
+export function autoFetchHint(os = platform(), firefoxFound = firefoxProfiles().length > 0) {
+    if (os === 'darwin')
+        return 'No browser was logged in, or the macOS Keychain prompt was denied.';
+    if (firefoxFound)
+        return 'A Firefox profile was found but held none of the cookies — log in at the provider in Firefox and retry.';
+    const why = os === 'win32'
+        ? 'Chrome/Edge cookies are sealed by App-Bound Encryption that only a SYSTEM process can unwrap'
+        : 'the Chromium keyring backends are not implemented here';
+    return `Auto-fetch supports Firefox only on this OS and no Firefox profile was found — ${why}.`;
+}

package/dist/cli.js

@@ -1,36 +1,67 @@
 #!/usr/bin/env node
 import { confirm, intro, isCancel, outro, password, select, text } from '@clack/prompts';
+import { autoFetchHint } from './browser.js';
 import { credential, loadConfig, saveCredential, saveRecentUrl, tryAutoFillCredentials } from './config.js';
 import { Conversion } from './conversion.js';
 import { PROVIDERS, inferSource, providerFor, targetKeys } from './registry.js';
 import { HELP_TEXT, parseArgs } from './args.js';
 function args() { return process.argv.slice(2); }
 // --- Credentials -----------------------------------------------------------
-// Fill one provider's credential: browser auto-fill first, then a manual paste. Persists what it
-// gets. Returns the credential, or null when the user cancels.
+// Why the browser read came back with nothing for this provider, and what to do instead. Every
+// auto-fetch failure says this, so the user never sees a bare "could not be fetched".
+function explainAutoFetchFailure(spec) {
+    const what = spec ? `${spec.label} cookies` : 'No credentials';
+    console.log(`✗ ${what} could not be read from your browser. ${autoFetchHint()}`);
+}
+// One manual paste, with where to find the value and what a correct one looks like.
+async function promptCredential(cfg, spec) {
+    console.log(`ℹ️ Where to find it: ${spec.credentialHint}`);
+    console.log(`   Looks like:      ${spec.credentialExample}`);
+    const entered = await password({ message: `Paste ${spec.credentialLabel}` });
+    if (isCancel(entered) || !entered)
+        return false;
+    await saveCredential(cfg, spec.key, String(entered).trim()); // pasted values carry stray whitespace
+    return true;
+}
+// Fill one provider's credential mid-conversion: browser auto-fill first, then a manual paste.
+// Persists what it gets. Returns the credential, or null when the user cancels.
 async function ensureCredential(cfg, spec) {
     if (credential(cfg, spec.key))
         return credential(cfg, spec.key);
     const filled = await tryAutoFillCredentials(cfg);
     if (filled.includes(spec.key))
         return credential(cfg, spec.key);
-    const entered = await password({ message: `${spec.credentialLabel} (${spec.credentialHint})` });
-    if (isCancel(entered) || !entered)
+    explainAutoFetchFailure(spec);
+    if (!(await promptCredential(cfg, spec)))
         return null;
-    await saveCredential(cfg, spec.key, String(entered));
     return credential(cfg, spec.key);
 }
-// Settings entry for one provider's credential: unlike ensureCredential this always asks, so a
-// saved-but-expired credential can be replaced. Proves it against the live service before saying so.
+// Settings entry for one provider's credential. The two ways in are offered as a choice rather than
+// auto-first-then-manual, so someone who knows the browser read will fail (or who wants to replace a
+// saved-but-expired value with a cookie of their own) can go straight to the paste. Auto-fetch here
+// overwrites, scoped to this provider, so an expired credential is actually replaced.
+// Proves whatever lands against the live service before saying it worked.
 async function reenterCredential(cfg, spec) {
-    warnLogin(spec.loginSite);
-    const filled = await tryAutoFillCredentials(cfg);
-    if (!filled.includes(spec.key)) {
-        const entered = await password({ message: `${spec.credentialLabel} (${spec.credentialHint})` });
-        if (isCancel(entered) || !entered)
+    const how = await select({
+        message: `${spec.credentialLabel}`,
+        options: [
+            { value: 'auto', label: 'Auto-fetch from browser' },
+            { value: 'manual', label: 'Paste cookies manually' },
+        ],
+    });
+    if (isCancel(how))
+        return;
+    if (how === 'auto') {
+        warnLogin(spec.loginSite);
+        if ((await tryAutoFillCredentials(cfg, true, spec.key)).includes(spec.key)) {
+            await report(cfg, spec);
             return;
-        await saveCredential(cfg, spec.key, String(entered));
+        }
+        explainAutoFetchFailure(spec);
+        console.log('   Paste it manually instead:');
     }
+    if (!(await promptCredential(cfg, spec)))
+        return;
     await report(cfg, spec);
 }
 // Check one provider's stored credential against the live service and say what happened.
@@ -241,16 +272,22 @@ async function runInteractive(options) {
         if (choice === 'autofetch') {
             warnLogin(PROVIDERS.map((p) => p.label).join(' & '));
             const filled = await tryAutoFillCredentials(cfg, true);
-            if (!filled.length) {
-                console.log('✗ No credentials could be fetched (browser not logged in / keychain denied).');
-                continue;
+            if (filled.length) {
+                console.log(`Fetched from browser: ${filled.join(', ')}. Checking…`);
+                for (const key of filled) {
+                    const spec = providerFor(key);
+                    if (spec)
+                        await report(cfg, spec);
+                }
             }
-            console.log(`Fetched from browser: ${filled.join(', ')}. Checking…`);
-            for (const key of filled) {
-                const spec = providerFor(key);
-                if (spec)
-                    await report(cfg, spec);
+            else {
+                explainAutoFetchFailure();
             }
+            // Whatever auto-fetch managed, the manual path is what closes the gap — name it and the menu
+            // entry that leads to it, rather than leaving the user at a dead end.
+            const missing = PROVIDERS.filter((p) => !credential(cfg, p.key));
+            if (missing.length)
+                console.log(`→ Still missing: ${missing.map((p) => p.label).join(', ')}. Add them from "Credentials: ${saved}/${PROVIDERS.length} saved" → pick the provider → "Paste cookies manually".`);
             continue;
         }
         if (choice === 'output') {

package/dist/config.js

@@ -10,10 +10,15 @@ const ENV_VAR = { deezer: 'DEEZER_ARL', spotify: 'SPOTIFY_DC', ytmusic: 'YTMUSIC
 // migrated (see #1): they are ignored, dropped on the next write, and the user re-fetches or
 // re-pastes — which costs one browser dialog.
 const LEGACY_KEYS = ['deezerArl', 'spotifyDc'];
+// XDG_CONFIG_HOME wins on every platform, Windows included: it is the explicit override, and a
+// Windows-only branch that ignored it left the tests sharing one real %APPDATA% dir instead of a
+// temp dir each, so state leaked between them.
 export function configDir() {
+    if (process.env.XDG_CONFIG_HOME)
+        return join(process.env.XDG_CONFIG_HOME, 'plx');
     if (platform() === 'win32')
         return join(process.env.APPDATA ?? join(homedir(), 'AppData', 'Roaming'), 'plx');
-    return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'plx');
+    return join(homedir(), '.config', 'plx');
 }
 const file = () => join(configDir(), 'credentials.json');
 async function loadStored() { try {
@@ -58,14 +63,16 @@ async function write(patch) {
 // Semi-auto: fill credentials from a logged-in browser (pops the macOS Keychain "Allow" dialog on
 // first use), persist what's found, and return the provider names filled. By default only fills
 // providers with no credential yet (env vars and stored credentials win); pass overwrite=true to
-// refetch and replace. Never throws — a denied keychain / TCC block just fills nothing, and the
-// caller falls back to the manual paste prompt.
-export async function tryAutoFillCredentials(cfg, overwrite = false) {
-    if (!overwrite && Object.keys(ENV_VAR).every((provider) => cfg.credentials[provider]))
+// refetch and replace, and `only` to confine that to one provider — the Credentials menu refetches
+// the provider being edited without quietly replacing the other two. Never throws — a denied
+// keychain / TCC block just fills nothing, and the caller falls back to the manual paste prompt.
+export async function tryAutoFillCredentials(cfg, overwrite = false, only) {
+    const wanted = only ? [only] : Object.keys(ENV_VAR);
+    if (!overwrite && wanted.every((provider) => cfg.credentials[provider]))
         return [];
     const filled = [];
     for (const [provider, value] of Object.entries(fetchBrowserCredentials())) {
-        if (!value || (!overwrite && cfg.credentials[provider]))
+        if (!value || !wanted.includes(provider) || (!overwrite && cfg.credentials[provider]))
             continue;
         cfg.credentials[provider] = value;
         filled.push(provider);

package/dist/registry.js

@@ -8,6 +8,7 @@ const spotify = {
     matches: ['open.spotify.com', 'spotify:playlist:'],
     credentialLabel: 'Spotify sp_dc',
     credentialHint: 'login open.spotify.com → F12 → Application → Cookies → sp_dc → copy value',
+    credentialExample: 'AQBv7pC3...9Kk  (the value only, ~150 chars, no "sp_dc=" prefix)',
     loginSite: 'Spotify (open.spotify.com)',
     anonymousRead: true,
     parseRef: async (ref) => parsePlaylistId(ref),
@@ -23,6 +24,7 @@ const deezer = {
     matches: ['deezer.com', 'link.deezer.com'],
     credentialLabel: 'Deezer ARL',
     credentialHint: 'login deezer.com → F12 → Application → Cookies → arl → copy value',
+    credentialExample: '3f9a1c...e7b2  (the value only, 192 hex chars, no "arl=" prefix)',
     loginSite: 'Deezer (deezer.com)',
     // Deezer's search is public, but reading a *playlist* goes through the authenticated GraphQL API.
     anonymousRead: false,
@@ -45,6 +47,7 @@ const ytmusic = {
     matches: ['music.youtube.com', 'youtube.com'],
     credentialLabel: 'YouTube Music cookies',
     credentialHint: 'login music.youtube.com → F12 → Network → any request → Request Headers → copy the whole "cookie:" value',
+    credentialExample: 'SAPISID=xxx; __Secure-3PAPISID=xxx; SID=xxx; __Secure-3PSID=xxx; __Secure-3PSIDTS=xxx; HSID=xxx; SSID=xxx; APISID=xxx  (one line, every cookie, SAPISID is required)',
     loginSite: 'YouTube Music (music.youtube.com)',
     anonymousRead: false,
     parseRef: async (ref) => parsePlaylistRef(ref),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plx-converter",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Convert playlists between Spotify, Deezer, and YouTube Music using your own browser session",
   "license": "MIT",
   "repository": {