@quenty/nevermore-cli-helpers 1.8.1 → 1.10.0

package/src/auth/cookie/index.ts

@@ -0,0 +1,271 @@
+/**
+ * Cookie auth and place creation for Roblox legacy APIs.
+ * Based on Mantle: https://github.com/blake-mealey/mantle
+ */
+
+import inquirer from 'inquirer';
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import { COOKIE_NAME } from './cookie-parser.js';
+import { readCookie as readWindowsCookie } from './windows.js';
+import { readCookie as readMacOSCookie } from './macos.js';
+import { readCookie as readLinuxCookie } from './linux.js';
+
+/**
+ * Resolve the .ROBLOSECURITY cookie for legacy Roblox API calls.
+ *
+ * Resolution order (matching Mantle's rbx_cookie crate):
+ * 1. ROBLOSECURITY environment variable
+ * 2. Platform credential store (Windows Credential Manager / macOS HTTPStorages / Wine Credential Manager)
+ * 3. Platform legacy store (Windows Registry / macOS plist)
+ * 4. Interactive prompt
+ */
+export async function getRobloxCookieAsync(): Promise<string> {
+  const envCookie = process.env.ROBLOSECURITY;
+  if (envCookie) {
+    return envCookie;
+  }
+
+  const platformCookie = readPlatformCookie();
+  if (platformCookie) {
+    return platformCookie;
+  }
+
+  // No interactive prompt in non-TTY environments (CI)
+  if (!process.stdin.isTTY) {
+    throw new Error(
+      'No .ROBLOSECURITY cookie available (set ROBLOSECURITY env var for CI)'
+    );
+  }
+
+  const { cookie } = await inquirer.prompt([
+    {
+      type: 'password',
+      name: 'cookie',
+      message: 'Enter your .ROBLOSECURITY cookie (from browser or Studio):',
+      mask: '*',
+      validate: (input: string) => input.length > 0 || 'Cookie cannot be empty',
+    },
+  ]);
+
+  return cookie;
+}
+
+function readPlatformCookie(): string | undefined {
+  switch (process.platform) {
+    case 'win32':
+      return readWindowsCookie();
+    case 'darwin':
+      return readMacOSCookie();
+    case 'linux':
+      return readLinuxCookie();
+    default:
+      return undefined;
+  }
+}
+
+interface CsrfFetchResult {
+  response: Response;
+  rotatedCookie?: string;
+}
+
+/**
+ * Extract a rotated .ROBLOSECURITY cookie from a response's set-cookie header.
+ */
+function extractRotatedCookie(response: Response): string | undefined {
+  const setCookie = response.headers.get('set-cookie');
+  if (!setCookie) {
+    return undefined;
+  }
+
+  // set-cookie may contain multiple cookies separated by commas (or multiple headers).
+  // Look for .ROBLOSECURITY=<value>.
+  const match = setCookie.match(/\.ROBLOSECURITY=([^;,\s]+)/);
+  return match?.[1];
+}
+
+/**
+ * Make a cookie-authenticated request to Roblox, handling CSRF token exchange,
+ * cookie rotation capture, and 429 rate-limit retries.
+ */
+async function fetchWithCsrfAsync(
+  url: string,
+  cookie: string,
+  options: RequestInit = {}
+): Promise<CsrfFetchResult> {
+  const headers: Record<string, string> = {
+    Cookie: `${COOKIE_NAME}=${cookie}`,
+    'User-Agent': 'Roblox/WinInet',
+    ...(options.headers as Record<string, string> | undefined),
+  };
+
+  let response = await fetch(url, {
+    ...options,
+    headers,
+  });
+
+  if (response.status === 403) {
+    const csrfToken = response.headers.get('x-csrf-token');
+    if (csrfToken) {
+      headers['X-CSRF-TOKEN'] = csrfToken;
+      response = await fetch(url, {
+        ...options,
+        headers,
+      });
+    }
+  }
+
+  // Retry once on rate limit
+  if (response.status === 429) {
+    const retryAfter = response.headers.get('retry-after');
+    const delaySec = retryAfter
+      ? Math.min(parseInt(retryAfter, 10) || 2, 30)
+      : 2;
+    OutputHelper.verbose(`Rate limited (429). Retrying after ${delaySec}s...`);
+    await new Promise((resolve) => setTimeout(resolve, delaySec * 1000));
+    response = await fetch(url, { ...options, headers });
+  }
+
+  const rotatedCookie = extractRotatedCookie(response);
+  if (rotatedCookie) {
+    OutputHelper.verbose(
+      'Captured rotated .ROBLOSECURITY cookie from response.'
+    );
+  }
+
+  return { response, rotatedCookie };
+}
+
+/**
+ * Create a new place in a universe using the legacy cookie-authenticated API.
+ * Returns the new place ID.
+ */
+export async function createPlaceInUniverseAsync(
+  cookie: string,
+  universeId: number,
+  placeName: string
+): Promise<number> {
+  OutputHelper.verbose(
+    `Creating place "${placeName}" in universe ${universeId}...`
+  );
+
+  const createResult = await fetchWithCsrfAsync(
+    `https://apis.roblox.com/universes/v1/user/universes/${universeId}/places`,
+    cookie,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ templatePlaceId: 95206881 }),
+    }
+  );
+
+  if (!createResult.response.ok) {
+    const text = await createResult.response.text();
+    throw new Error(
+      `Failed to create place: ${createResult.response.status} ${createResult.response.statusText}: ${text}`
+    );
+  }
+
+  const createData = (await createResult.response.json()) as {
+    placeId: number;
+  };
+  const placeId = createData.placeId;
+
+  // Use rotated cookie if the create request triggered rotation
+  const { response: renameResponse } = await fetchWithCsrfAsync(
+    `https://develop.roblox.com/v2/places/${placeId}`,
+    createResult.rotatedCookie ?? cookie,
+    {
+      method: 'PATCH',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ name: placeName }),
+    }
+  );
+
+  if (!renameResponse.ok) {
+    OutputHelper.warn(
+      `Place created (${placeId}) but rename failed — you can rename it manually.`
+    );
+  }
+
+  OutputHelper.verbose(`Created place "${placeName}" — ID: ${placeId}`);
+  return placeId;
+}
+
+export interface CookieValidationResult {
+  valid: boolean;
+  reason?: 'invalid' | 'network_error';
+  status?: number;
+}
+
+/**
+ * Validates the ROBLOSECURITY cookie against the Roblox API.
+ * Returns a result indicating whether the cookie is valid.
+ * Network errors are treated as "unknown" (not invalid) so callers
+ * can decide whether to continue in offline scenarios.
+ */
+export async function validateCookieAsync(
+  cookie: string
+): Promise<CookieValidationResult> {
+  try {
+    const response = await fetch(
+      'https://users.roblox.com/v1/users/authenticated',
+      {
+        headers: {
+          Cookie: `.ROBLOSECURITY=${cookie}`,
+        },
+      }
+    );
+
+    if (response.status !== 200) {
+      return { valid: false, reason: 'invalid', status: response.status };
+    }
+
+    return { valid: true };
+  } catch {
+    return { valid: false, reason: 'network_error' };
+  }
+}
+
+export interface RenamePlaceResult {
+  success: boolean;
+  reason?: 'no_cookie' | 'api_error';
+  status?: number;
+}
+
+/**
+ * Try to rename an existing place via the develop.roblox.com API.
+ */
+export async function tryRenamePlaceAsync(
+  placeId: number,
+  placeName: string
+): Promise<RenamePlaceResult> {
+  let cookie: string;
+  try {
+    cookie = await getRobloxCookieAsync();
+  } catch {
+    return { success: false, reason: 'no_cookie' };
+  }
+
+  const { response } = await fetchWithCsrfAsync(
+    `https://develop.roblox.com/v2/places/${placeId}`,
+    cookie,
+    {
+      method: 'PATCH',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ name: placeName }),
+    }
+  );
+
+  if (response.ok) {
+    OutputHelper.verbose(`Renamed place ${placeId} to "${placeName}"`);
+    return { success: true };
+  }
+
+  return { success: false, reason: 'api_error', status: response.status };
+}

package/src/auth/cookie/linux.ts

@@ -0,0 +1,175 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import { COOKIE_NAME } from './cookie-parser.js';
+
+/**
+ * Read .ROBLOSECURITY from Wine's Credential Manager stored in the Wine
+ * registry file ($WINEPREFIX/user.reg).
+ *
+ * Wine stores Windows Credential Manager entries as registry keys under
+ * [Software\\Wine\\Credential Manager]. Each credential target becomes a
+ * subkey with hex-encoded blob values.
+ *
+ * Resolution order (mirrors windows.ts):
+ * 1. Modern: user-specific credential (RobloxStudioAuth.ROBLOSECURITY{userId})
+ * 2. Legacy: RobloxStudioAuth.ROBLOSECURITY (no user suffix)
+ */
+export function readCookie(): string | undefined {
+  const userReg = getWineUserRegPath();
+  if (!userReg || !fs.existsSync(userReg)) {
+    return undefined;
+  }
+
+  let regContent: string;
+  try {
+    regContent = fs.readFileSync(userReg, 'utf-8');
+  } catch {
+    return undefined;
+  }
+
+  const credentials = parseWineCredentials(regContent);
+
+  // Modern: user-specific credential
+  const userId = credentials.get(
+    'https://www.roblox.com:RobloxStudioAuthuserid'
+  );
+  if (userId) {
+    const cookie = credentials.get(
+      `https://www.roblox.com:RobloxStudioAuth${COOKIE_NAME}${userId}`
+    );
+    if (cookie) {
+      OutputHelper.verbose(
+        `Loaded cookie from Wine Credential Manager (user ${userId}).`
+      );
+      return cookie;
+    }
+  }
+
+  // Legacy: no user suffix
+  const legacyCookie = credentials.get(
+    `https://www.roblox.com:RobloxStudioAuth${COOKIE_NAME}`
+  );
+  if (legacyCookie) {
+    OutputHelper.verbose(
+      'Loaded cookie from Wine Credential Manager (legacy).'
+    );
+    return legacyCookie;
+  }
+
+  return undefined;
+}
+
+function getWineUserRegPath(): string | undefined {
+  const wineprefix = process.env.WINEPREFIX || path.join(os.homedir(), '.wine');
+  return path.join(wineprefix, 'user.reg');
+}
+
+/**
+ * Parse Wine's user.reg file for Credential Manager entries.
+ *
+ * Wine stores credentials under registry keys like:
+ *   [Software\\Wine\\Credential Manager]
+ *
+ * Each credential is a named value where the name is the target and the
+ * value is a hex-encoded binary blob. The credential blob (the actual
+ * secret) is stored as UTF-8 bytes within the binary structure.
+ *
+ * Returns a Map of target name -> credential value (decoded string).
+ */
+function parseWineCredentials(regContent: string): Map<string, string> {
+  const credentials = new Map<string, string>();
+
+  // Wine Credential Manager stores creds as individual hex blobs under
+  // [Software\\Wine\\Credential Manager]. The key format is:
+  //   "Target Name"=hex:xx,xx,xx,...
+  // The hex blob is a serialized CREDENTIAL struct.
+  const credSectionMatch = regContent.match(
+    /\[Software\\\\Wine\\\\Credential Manager\]([\s\S]*?)(?=\n\[|$)/i
+  );
+  if (!credSectionMatch) {
+    return credentials;
+  }
+
+  const section = credSectionMatch[1];
+
+  // Match each credential entry: "TargetName"=hex:bytes
+  const entryRegex = /^"(.+?)"=hex:(.+)$/gm;
+  let match;
+  while ((match = entryRegex.exec(section)) !== null) {
+    const targetName = unescapeRegString(match[1]);
+    const hexStr = match[2].replace(/\\\n\s*/g, '').replace(/,/g, '');
+
+    try {
+      const blob = Buffer.from(hexStr, 'hex');
+      const value = extractCredentialBlob(blob);
+      if (value) {
+        credentials.set(targetName, value);
+      }
+    } catch {
+      // Malformed hex data
+    }
+  }
+
+  return credentials;
+}
+
+/**
+ * Extract the credential value from a Wine serialized CREDENTIAL blob.
+ *
+ * The blob layout follows the Windows CREDENTIAL struct. The credential
+ * value (CredentialBlob) is stored as UTF-8 bytes. We look for the
+ * actual cookie/value content by searching for known patterns.
+ */
+function extractCredentialBlob(blob: Buffer): string | undefined {
+  // Wine's serialized credential format stores the blob data inline.
+  // The simplest approach: the credential value for Roblox entries is
+  // plain UTF-8 text. Try to find it by looking for cookie-like content
+  // or numeric user IDs.
+
+  // Try interpreting the entire blob as UTF-8 and looking for the value
+  const text = blob.toString('utf-8');
+
+  // For simple values (user IDs, cookie names), the blob may just be
+  // the raw UTF-8 string
+  if (text && isPrintableAscii(text)) {
+    return text;
+  }
+
+  // For structured blobs, search for the credential data section.
+  // Wine writes a serialized struct — scan for the longest printable
+  // ASCII substring that looks like a credential value.
+  let best = '';
+  let current = '';
+  for (let i = 0; i < blob.length; i++) {
+    const byte = blob[i];
+    if (byte >= 0x20 && byte < 0x7f) {
+      current += String.fromCharCode(byte);
+    } else {
+      if (current.length > best.length) {
+        best = current;
+      }
+      current = '';
+    }
+  }
+  if (current.length > best.length) {
+    best = current;
+  }
+
+  return best.length > 0 ? best : undefined;
+}
+
+function isPrintableAscii(str: string): boolean {
+  for (let i = 0; i < str.length; i++) {
+    const code = str.charCodeAt(i);
+    if (code < 0x20 || code > 0x7e) {
+      return false;
+    }
+  }
+  return str.length > 0;
+}
+
+function unescapeRegString(str: string): string {
+  return str.replace(/\\\\/g, '\\');
+}

package/src/auth/cookie/macos.ts

@@ -0,0 +1,88 @@
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { OutputHelper } from '@quenty/cli-output-helpers';
+
+/**
+ * Read from ~/Library/HTTPStorages/com.Roblox.RobloxStudio.binarycookies.
+ * This is a binary format — we shell out to Python to parse it since Node
+ * doesn't have a native binarycookies parser.
+ */
+function readFromHTTPStorages(): string | undefined {
+  const cookiePath = path.join(
+    os.homedir(),
+    'Library/HTTPStorages/com.Roblox.RobloxStudio.binarycookies'
+  );
+
+  if (!fs.existsSync(cookiePath)) {
+    return undefined;
+  }
+
+  const pyScript = `
+import struct, sys
+with open(sys.argv[1], 'rb') as f:
+    data = f.read()
+idx = data.find(b'_|WARNING')
+if idx >= 0:
+    end = data.find(b'\\x00', idx)
+    if end < 0: end = len(data)
+    print(data[idx:end].decode('utf-8', errors='ignore'))
+`.trim();
+
+  try {
+    const result = execSync(
+      `python3 -c ${JSON.stringify(pyScript)} ${JSON.stringify(cookiePath)}`,
+      { encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] }
+    ).trim();
+
+    if (result && result.startsWith('_|')) {
+      OutputHelper.verbose('Loaded cookie from macOS HTTPStorages.');
+      return result;
+    }
+  } catch {
+    // Python parse failed
+  }
+
+  return undefined;
+}
+
+function readFromPlist(): string | undefined {
+  const plistPath = path.join(
+    os.homedir(),
+    'Library/Preferences/com.roblox.RobloxStudioBrowser.plist'
+  );
+
+  if (!fs.existsSync(plistPath)) {
+    return undefined;
+  }
+
+  try {
+    const result = execSync(
+      `defaults read com.roblox.RobloxStudioBrowser 2>/dev/null | grep ROBLOSECURITY`,
+      { encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] }
+    ).trim();
+
+    if (result) {
+      const cookieMatch = result.match(/COOK::<(.+?)>/);
+      if (cookieMatch) {
+        OutputHelper.verbose('Loaded cookie from macOS plist.');
+        return cookieMatch[1];
+      }
+
+      const valueMatch = result.match(/"([^"]*_\|[^"]*)"/);
+      if (valueMatch) {
+        OutputHelper.verbose('Loaded cookie from macOS plist.');
+        return valueMatch[1];
+      }
+    }
+  } catch {
+    // plist read failed
+  }
+
+  return undefined;
+}
+
+export function readCookie(): string | undefined {
+  return readFromHTTPStorages() ?? readFromPlist();
+}

package/src/auth/cookie/validate-cookie.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+import { validateCookieAsync } from './index.js';
+
+describe('validateCookieAsync', () => {
+  const originalFetch = globalThis.fetch;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it('returns valid when cookie is accepted (HTTP 200)', async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({ status: 200 });
+
+    const result = await validateCookieAsync('valid-cookie');
+
+    expect(result).toEqual({ valid: true });
+  });
+
+  it('returns invalid with status when cookie is rejected (HTTP 401)', async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({ status: 401 });
+
+    const result = await validateCookieAsync('expired-cookie');
+
+    expect(result).toEqual({ valid: false, reason: 'invalid', status: 401 });
+  });
+
+  it('returns network_error when fetch throws', async () => {
+    globalThis.fetch = vi.fn().mockRejectedValue(new Error('network error'));
+
+    const result = await validateCookieAsync('some-cookie');
+
+    expect(result).toEqual({ valid: false, reason: 'network_error' });
+  });
+});

package/src/auth/cookie/windows.ts

@@ -0,0 +1,96 @@
+import { execSync } from 'child_process';
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import { COOKIE_NAME, parseStudioCookieValue } from './cookie-parser.js';
+
+/**
+ * Read a generic credential from Windows Credential Manager via CredRead.
+ * The blob is decoded as UTF-8 (matching Mantle's wincred.rs).
+ */
+function winCredRead(target: string): string | undefined {
+  const escapedTarget = target.replace(/'/g, "''");
+  const script = [
+    `Add-Type -TypeDefinition '`,
+    `using System; using System.Runtime.InteropServices; using System.Text;`,
+    `public class NevCred {`,
+    `  [DllImport("advapi32.dll",SetLastError=true,CharSet=CharSet.Unicode)]`,
+    `  public static extern bool CredRead(string t,int ty,int f,out IntPtr c);`,
+    `  [DllImport("advapi32.dll",SetLastError=true)]`,
+    `  public static extern bool CredFree(IntPtr c);`,
+    `  [StructLayout(LayoutKind.Sequential,CharSet=CharSet.Unicode)]`,
+    `  public struct CRED { public int F; public int T; public string TN; public string Co;`,
+    `    public System.Runtime.InteropServices.ComTypes.FILETIME LW;`,
+    `    public int CBS; public IntPtr CB; public int P; public int AC; public IntPtr At;`,
+    `    public string TA; public string UN; }`,
+    `  public static string Read(string t) {`,
+    `    IntPtr p; if(!CredRead(t,1,0,out p)) return null;`,
+    `    try { CRED c=(CRED)Marshal.PtrToStructure(p,typeof(CRED));`,
+    `      if(c.CBS<=0) return "";`,
+    `      byte[] b=new byte[c.CBS]; Marshal.Copy(c.CB,b,0,c.CBS);`,
+    `      return Encoding.UTF8.GetString(b);`,
+    `    } finally { CredFree(p); } } }`,
+    `'; [NevCred]::Read('${escapedTarget}')`,
+  ].join(' ');
+
+  try {
+    const result = execSync(
+      `powershell -NoProfile -ExecutionPolicy Bypass -Command "${script.replace(
+        /"/g,
+        '\\"'
+      )}"`,
+      { encoding: 'utf-8', timeout: 10000, stdio: ['pipe', 'pipe', 'pipe'] }
+    ).trim();
+    return result.length > 0 ? result : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function readFromRegistry(): string | undefined {
+  try {
+    const script = `(Get-ItemProperty -Path 'HKCU:\\Software\\Roblox\\RobloxStudioBrowser\\roblox.com' -Name '${COOKIE_NAME}' -ErrorAction SilentlyContinue).'${COOKIE_NAME}'`;
+    const result = execSync(
+      `powershell -NoProfile -ExecutionPolicy Bypass -Command "${script}"`,
+      { encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] }
+    ).trim();
+
+    if (result && result.length > 10) {
+      const parsed = parseStudioCookieValue(result);
+      if (parsed) {
+        OutputHelper.verbose('Loaded cookie from Windows Registry.');
+        return parsed;
+      }
+    }
+  } catch {
+    // Registry read failed
+  }
+
+  return undefined;
+}
+
+export function readCookie(): string | undefined {
+  // Modern Studio: user-specific credential
+  const userId = winCredRead('https://www.roblox.com:RobloxStudioAuthuserid');
+  if (userId) {
+    const cookie = winCredRead(
+      `https://www.roblox.com:RobloxStudioAuth${COOKIE_NAME}${userId}`
+    );
+    if (cookie) {
+      OutputHelper.verbose(
+        `Loaded cookie from Windows Credentials (user ${userId}).`
+      );
+      return cookie;
+    }
+  }
+
+  // Legacy credential (no user ID suffix)
+  const legacyCookie = winCredRead(
+    `https://www.roblox.com:RobloxStudioAuth${COOKIE_NAME}`
+  );
+  if (legacyCookie) {
+    OutputHelper.verbose('Loaded cookie from Windows Credentials (legacy).');
+    return legacyCookie;
+  }
+
+  // Oldest fallback: Windows Registry
+  return readFromRegistry();
+}