ytstats 0.1.0

package/src/auth/credentials.js

@@ -0,0 +1,172 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJson, writeJson, removeFile } from '../config/store.js';
+import { CREDENTIALS_FILE } from '../config/paths.js';
+import { YtStatsError, ERROR_CODES, SETUP_GUIDE, fail } from '../errors.js';
+import { DIAGNOSTICS, diagnose } from '../diagnostics.js';
+
+/**
+ * Normalise any of the shapes Google hands out into { clientId, clientSecret }.
+ * Accepts the Desktop-app ("installed"), web, and already-flat forms.
+ */
+export function parseClientSecret(raw) {
+  if (!raw || typeof raw !== 'object') {
+    throw new YtStatsError('Credential file is not a JSON object.', {
+      code: ERROR_CODES.INVALID_CREDENTIALS,
+    });
+  }
+
+  if (raw.type === 'service_account') {
+    throw fail(DIAGNOSTICS.AUTH_SERVICE_ACCOUNT, {
+      detail: raw.client_email ? `Key belongs to ${raw.client_email}` : undefined,
+    });
+  }
+
+  const node = raw.installed || raw.web || raw;
+  const clientId = node.client_id ?? node.clientId;
+  const clientSecret = node.client_secret ?? node.clientSecret;
+
+  if (!clientId) throw fail(DIAGNOSTICS.AUTH_CREDENTIALS_MALFORMED, { detail: 'No client_id in the file' });
+  if (!clientSecret) throw fail(DIAGNOSTICS.AUTH_CREDENTIALS_MALFORMED, { detail: 'No client_secret in the file' });
+
+  return { clientId, clientSecret };
+}
+
+function readClientSecretFile(file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf-8');
+  } catch {
+    throw fail(DIAGNOSTICS.AUTH_CREDENTIALS_NOT_FOUND, { value: file, flag: '--client-secret' });
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw fail(DIAGNOSTICS.AUTH_CREDENTIALS_MALFORMED, {
+      value: file, detail: 'File is not valid JSON',
+    });
+  }
+
+  return parseClientSecret(parsed);
+}
+
+/**
+ * Look for a downloaded client secret in a directory. Google names these
+ * client_secret_<numbers>-<hash>.apps.googleusercontent.com.json, so we glob the
+ * prefix. Exact `client_secret.json` wins; otherwise sort for determinism.
+ */
+export function discoverClientSecretFile(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return null;
+  }
+
+  const candidates = entries
+    .filter(f => f.startsWith('client_secret') && f.endsWith('.json'))
+    .sort();
+  if (candidates.length === 0) return null;
+
+  const exact = candidates.find(f => f === 'client_secret.json');
+  return path.join(dir, exact ?? candidates[0]);
+}
+
+/** Google issues IDs shaped <project-number>-<hash>.apps.googleusercontent.com */
+const CLIENT_ID_SUFFIX = '.apps.googleusercontent.com';
+const CANONICAL_CLIENT_ID = /^\d+-[A-Za-z0-9_]+\.apps\.googleusercontent\.com$/;
+
+/**
+ * Check the client ID before it is ever sent to Google.
+ *
+ * A malformed client ID does not produce an API error — Google renders
+ * "Access blocked: Authorization Error" in the browser and simply never
+ * redirects, so the CLI would block until its timeout with no useful diagnosis.
+ * Catching it here turns a five-minute hang into an instant, precise failure.
+ *
+ * Returns a warning diagnostic for merely-unusual IDs; throws for impossible ones.
+ */
+export function validateClientId(clientId) {
+  const id = String(clientId ?? '');
+
+  if (!id.endsWith(CLIENT_ID_SUFFIX)) {
+    throw fail(DIAGNOSTICS.AUTH_CLIENT_ID_INVALID, {
+      value: id.length > 60 ? `${id.slice(0, 57)}...` : id,
+      expected: `an ID ending in ${CLIENT_ID_SUFFIX}`,
+    });
+  }
+
+  // Legacy clients occasionally deviate, so an unusual shape is a warning rather
+  // than a hard failure — being wrong here must not lock anyone out.
+  if (!CANONICAL_CLIENT_ID.test(id)) {
+    return diagnose(DIAGNOSTICS.AUTH_CLIENT_ID_SUSPICIOUS, {
+      value: id,
+      expected: '<project-number>-<hash>.apps.googleusercontent.com',
+    });
+  }
+
+  return null;
+}
+
+export function loadStoredCredentials() {
+  const stored = readJson(CREDENTIALS_FILE);
+  if (!stored?.clientId || !stored?.clientSecret) return null;
+  return stored;
+}
+
+export function saveCredentials({ clientId, clientSecret, source }) {
+  writeJson(CREDENTIALS_FILE, {
+    version: 1,
+    clientId,
+    clientSecret,
+    source: source ?? 'login',
+    savedAt: new Date().toISOString(),
+  });
+  return { clientId, clientSecret };
+}
+
+export function clearCredentials() {
+  return removeFile(CREDENTIALS_FILE);
+}
+
+/**
+ * Resolve BYO OAuth client credentials.
+ *
+ * Precedence:
+ *   1. --client-secret <file>
+ *   2. YTSTATS_CLIENT_ID + YTSTATS_CLIENT_SECRET (both required)
+ *   3. credentials.json saved by a previous `ytstats login`
+ *   4. client_secret*.json auto-discovered in the working directory
+ *
+ * Returns { clientId, clientSecret, source }. `source` is for display only and
+ * never contains the secret.
+ */
+export function resolveCredentials({ clientSecretPath, env = process.env, cwd = process.cwd() } = {}) {
+  if (clientSecretPath) {
+    return { ...readClientSecretFile(clientSecretPath), source: clientSecretPath };
+  }
+
+  if (env.YTSTATS_CLIENT_ID && env.YTSTATS_CLIENT_SECRET) {
+    return {
+      clientId: env.YTSTATS_CLIENT_ID,
+      clientSecret: env.YTSTATS_CLIENT_SECRET,
+      source: 'environment',
+    };
+  }
+
+  const stored = loadStoredCredentials();
+  if (stored) {
+    return { clientId: stored.clientId, clientSecret: stored.clientSecret, source: 'stored' };
+  }
+
+  const discovered = discoverClientSecretFile(cwd);
+  if (discovered) {
+    return { ...readClientSecretFile(discovered), source: discovered };
+  }
+
+  throw fail(DIAGNOSTICS.AUTH_NO_CREDENTIALS, {
+    detail: `Searched: --client-secret, YTSTATS_CLIENT_ID/SECRET env vars, stored credentials, and client_secret*.json in ${cwd}`,
+  });
+}

package/src/auth/oauth.js

@@ -0,0 +1,167 @@
+import http from 'node:http';
+import crypto from 'node:crypto';
+import { URL } from 'node:url';
+import { YtStatsError, ERROR_CODES, fail } from '../errors.js';
+import { DIAGNOSTICS } from '../diagnostics.js';
+
+/** Read-only scopes only. ytstats never requests write access to a channel. */
+export const SCOPES = Object.freeze([
+  'https://www.googleapis.com/auth/youtube.readonly',
+  'https://www.googleapis.com/auth/yt-analytics.readonly',
+  'https://www.googleapis.com/auth/yt-analytics-monetary.readonly',
+]);
+
+const AUTH_ENDPOINT = 'https://accounts.google.com/o/oauth2/v2/auth';
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+
+const base64url = buf =>
+  buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+
+/**
+ * RFC 7636 PKCE pair. Protects the authorization code against interception by
+ * another local process racing us on the loopback port.
+ */
+export function createPkcePair() {
+  const verifier = base64url(crypto.randomBytes(64)).slice(0, 128);
+  const challenge = base64url(crypto.createHash('sha256').update(verifier).digest());
+  return { verifier, challenge };
+}
+
+/** Unguessable value tying the callback back to this specific login attempt. */
+export function createState() {
+  return base64url(crypto.randomBytes(24));
+}
+
+export function buildAuthUrl({ clientId, redirectUri, state, codeChallenge, scopes = SCOPES }) {
+  const url = new URL(AUTH_ENDPOINT);
+  url.searchParams.set('client_id', clientId);
+  url.searchParams.set('redirect_uri', redirectUri);
+  url.searchParams.set('response_type', 'code');
+  url.searchParams.set('scope', scopes.join(' '));
+  url.searchParams.set('state', state);
+  url.searchParams.set('code_challenge', codeChallenge);
+  url.searchParams.set('code_challenge_method', 'S256');
+  // offline + consent are what make Google return a refresh token.
+  url.searchParams.set('access_type', 'offline');
+  url.searchParams.set('prompt', 'consent');
+  url.searchParams.set('include_granted_scopes', 'true');
+  return url.toString();
+}
+
+function page(title, body, accent) {
+  return `<!doctype html><html><head><meta charset="utf-8"><title>${title}</title>
+<style>
+ body{font:16px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;
+      display:flex;align-items:center;justify-content:center;height:100vh;margin:0;
+      background:#0f1115;color:#e6e6e6}
+ .card{max-width:30rem;padding:2.5rem;text-align:center}
+ h1{font-size:1.35rem;margin:0 0 .5rem;color:${accent}}
+ p{margin:0;color:#9aa0a6}
+</style></head><body><div class="card"><h1>${title}</h1><p>${body}</p></div></body></html>`;
+}
+
+const SUCCESS_PAGE = page('Signed in to ytstats', 'You can close this tab and return to your terminal.', '#4ade80');
+const failPage = reason => page('Sign-in failed', reason, '#f87171');
+
+/**
+ * Start the local callback listener.
+ *
+ * Binds 127.0.0.1 on an ephemeral port — never 0.0.0.0, so nothing off-machine can
+ * reach it. The returned promise settles on the first legitimate callback.
+ */
+export async function startLoopbackServer({ state, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  let resolveCode, rejectCode;
+  const codePromise = new Promise((res, rej) => { resolveCode = res; rejectCode = rej; });
+
+  let settled = false;
+  const settle = (fn, value) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    fn(value);
+  };
+
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url, 'http://127.0.0.1');
+
+    // The browser asks for this unprompted; it is not the callback.
+    if (url.pathname === '/favicon.ico') {
+      res.writeHead(404).end();
+      return;
+    }
+    if (url.pathname !== '/' && url.pathname !== '/callback') {
+      res.writeHead(404).end();
+      return;
+    }
+
+    const params = url.searchParams;
+    const error = params.get('error');
+    const code = params.get('code');
+    const returnedState = params.get('state');
+
+    if (error) {
+      const denied = error === 'access_denied';
+      res.writeHead(400, { 'content-type': 'text/html; charset=utf-8' })
+        .end(failPage(denied ? 'You declined the permission request.' : `Google returned: ${error}`));
+      settle(rejectCode, denied
+        ? fail(DIAGNOSTICS.AUTH_CONSENT_DECLINED, { detail: `Google returned: ${error}` })
+        : fail(DIAGNOSTICS.AUTH_STATE_MISMATCH, { detail: `Google returned: ${error}` }));
+      return;
+    }
+
+    // Constant-time compare so the state cannot be probed byte by byte.
+    if (!returnedState || !safeEqual(returnedState, state)) {
+      res.writeHead(400, { 'content-type': 'text/html; charset=utf-8' })
+        .end(failPage('Security check failed. Please start the login again.'));
+      settle(rejectCode, fail(DIAGNOSTICS.AUTH_STATE_MISMATCH));
+      return;
+    }
+
+    if (!code) {
+      res.writeHead(400, { 'content-type': 'text/html; charset=utf-8' })
+        .end(failPage('No authorization code was returned.'));
+      settle(rejectCode, fail(DIAGNOSTICS.AUTH_STATE_MISMATCH, { detail: 'No authorization code in the callback' }));
+      return;
+    }
+
+    // The success page deliberately contains no code/token material.
+    res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' }).end(SUCCESS_PAGE);
+    settle(resolveCode, { code });
+  });
+
+  const timer = setTimeout(() => {
+    settle(rejectCode, fail(DIAGNOSTICS.AUTH_TIMEOUT));
+  }, timeoutMs);
+  timer.unref?.();
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', resolve);
+  });
+
+  const { port, address } = server.address();
+  let closed = false;
+
+  return {
+    port,
+    address,
+    redirectUri: `http://127.0.0.1:${port}`,
+    waitForCode: () => codePromise,
+    close() {
+      if (closed) return;
+      closed = true;
+      clearTimeout(timer);
+      server.close();
+      // Nothing should be waiting, but never leave a dangling promise.
+      settle(rejectCode, new YtStatsError('Login cancelled.', { code: ERROR_CODES.AUTH_FAILED }));
+      codePromise.catch(() => {});
+    },
+  };
+}
+
+function safeEqual(a, b) {
+  const ab = Buffer.from(String(a));
+  const bb = Buffer.from(String(b));
+  if (ab.length !== bb.length) return false;
+  return crypto.timingSafeEqual(ab, bb);
+}

package/src/auth/session.js

@@ -0,0 +1,257 @@
+import readline from 'node:readline';
+import { google } from 'googleapis';
+import open from 'open';
+import { resolveCredentials, saveCredentials, clearCredentials, validateClientId } from './credentials.js';
+import { saveAccount, loadAccount, removeAccount, clearAllAccounts, listAccounts } from './tokens.js';
+import { createPkcePair, createState, buildAuthUrl, startLoopbackServer, SCOPES } from './oauth.js';
+import { YtStatsError, ERROR_CODES, mapGoogleError, fail } from '../errors.js';
+import { DIAGNOSTICS } from '../diagnostics.js';
+
+/**
+ * Everything that touches the network or the terminal is injected, so the whole
+ * session layer is testable without hitting Google or opening a browser.
+ */
+function defaultDeps() {
+  return {
+    OAuth2: google.auth.OAuth2,
+    startLoopbackServer,
+    openBrowser: url => open(url),
+    fetchIdentity: defaultFetchIdentity,
+    promptForRedirectUrl: defaultPrompt,
+    log: msg => process.stderr.write(msg + '\n'),
+  };
+}
+
+async function defaultFetchIdentity(client) {
+  const yt = google.youtube({ version: 'v3', auth: client });
+  const res = await yt.channels.list({ part: 'snippet,contentDetails', mine: true });
+  const channel = res.data.items?.[0];
+  if (!channel) return null;
+  return {
+    channelId: channel.id,
+    channelTitle: channel.snippet?.title ?? null,
+    customUrl: channel.snippet?.customUrl ?? null,
+    uploadsPlaylistId: channel.contentDetails?.relatedPlaylists?.uploads ?? null,
+  };
+}
+
+function defaultPrompt(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  return new Promise(resolve => rl.question(question, answer => { rl.close(); resolve(answer); }));
+}
+
+function newClient(deps, { clientId, clientSecret }, redirectUri) {
+  const Ctor = deps.OAuth2;
+  return new Ctor(clientId, clientSecret, redirectUri);
+}
+
+/**
+ * Build an OAuth client bound to a stored account, wired so that any token Google
+ * rotates during the process lifetime is written back to disk.
+ */
+export function getAuthenticatedClient({ account: selector, clientSecretPath, env, cwd, deps: injected } = {}) {
+  const deps = { ...defaultDeps(), ...injected };
+
+  // Distinguish the ways "not authenticated" can happen — each has a different
+  // fix, so each gets its own diagnostic.
+  //
+  // Credentials are diagnosed BEFORE tokens: an OAuth client is the prerequisite
+  // for logging in at all, so reporting "not signed in" to someone who has not
+  // yet created a Google Cloud project sends them down the wrong recovery path.
+  const credentials = resolveCredentials({ clientSecretPath, env, cwd });
+
+  const account = loadAccount(selector);
+  if (!account) {
+    const known = listAccounts();
+    if (selector) {
+      throw fail(DIAGNOSTICS.AUTH_ACCOUNT_UNKNOWN, {
+        account: selector,
+        allowed: known.map(a => a.channelId),
+        detail: known.length
+          ? `Signed in: ${known.map(a => `${a.channelTitle ?? a.channelId} (${a.channelId})`).join(', ')}`
+          : 'No channels are signed in on this machine.',
+      });
+    }
+    throw fail(DIAGNOSTICS.AUTH_NO_TOKENS, {
+      detail: `OAuth client resolved from: ${credentials.source}`,
+    });
+  }
+  const client = newClient(deps, credentials, 'http://127.0.0.1');
+  client.setCredentials(account.tokens);
+
+  // Google omits refresh_token on a refresh response; saveAccount merges rather
+  // than replaces, so the long-lived token survives.
+  client.on('tokens', tokens => {
+    try {
+      saveAccount({
+        channelId: account.channelId,
+        channelTitle: account.channelTitle,
+        customUrl: account.customUrl,
+        tokens,
+      });
+    } catch {
+      // A read-only config dir must not break an otherwise working command.
+    }
+  });
+
+  return { client, account, credentials };
+}
+
+/**
+ * Interactive login. Default path opens the browser and captures the callback on
+ * 127.0.0.1; `noBrowser` falls back to printing the URL and reading the pasted
+ * redirect (for SSH/headless).
+ */
+export async function login({
+  credentials: provided,
+  clientSecretPath,
+  noBrowser = false,
+  env,
+  cwd,
+  timeoutMs,
+  deps: injected,
+} = {}) {
+  const deps = { ...defaultDeps(), ...injected };
+  const credentials = provided ?? resolveCredentials({ clientSecretPath, env, cwd });
+
+  // Validate before opening a browser. Google does not reject a bad client ID via
+  // the API — it renders "Access blocked" in the browser and never redirects, so
+  // without this the command would block until timeout with a misleading cause.
+  const idWarning = validateClientId(credentials.clientId);
+  if (idWarning) deps.log(`warning: ${idWarning.title} — ${idWarning.detail}`);
+
+  const { verifier, challenge } = createPkcePair();
+  const state = createState();
+
+  const { code, redirectUri } = noBrowser
+    ? await pasteFlow({ deps, credentials, state, challenge })
+    : await browserFlow({ deps, credentials, state, challenge, timeoutMs });
+
+  const client = newClient(deps, credentials, redirectUri);
+
+  let tokens;
+  try {
+    ({ tokens } = await client.getToken({ code, codeVerifier: verifier, redirect_uri: redirectUri }));
+  } catch (err) {
+    throw mapGoogleError(err);
+  }
+  client.setCredentials(tokens);
+
+  // Identify the channel before persisting anything, so a failed lookup cannot
+  // leave a half-written account behind.
+  let identity;
+  try {
+    identity = await deps.fetchIdentity(client);
+  } catch (err) {
+    throw mapGoogleError(err);
+  }
+
+  if (!identity?.channelId) throw fail(DIAGNOSTICS.AUTH_NO_CHANNEL);
+
+  saveCredentials({ ...credentials, source: credentials.source });
+  saveAccount({
+    channelId: identity.channelId,
+    channelTitle: identity.channelTitle,
+    customUrl: identity.customUrl,
+    tokens,
+  });
+
+  return identity;
+}
+
+async function browserFlow({ deps, credentials, state, challenge, timeoutMs }) {
+  const server = await deps.startLoopbackServer({ state, timeoutMs });
+  try {
+    const authUrl = buildAuthUrl({
+      clientId: credentials.clientId,
+      redirectUri: server.redirectUri,
+      state,
+      codeChallenge: challenge,
+      scopes: SCOPES,
+    });
+
+    deps.log('Opening your browser to sign in with Google...');
+    deps.log(`If it does not open, paste this URL:\n${authUrl}\n`);
+    await deps.openBrowser(authUrl);
+
+    const { code } = await server.waitForCode();
+    return { code, redirectUri: server.redirectUri };
+  } finally {
+    server.close();
+  }
+}
+
+async function pasteFlow({ deps, credentials, state, challenge }) {
+  // No loopback listener here, so Google's redirect will simply fail to load and
+  // the user copies the URL out of the address bar.
+  const redirectUri = 'http://127.0.0.1:1';
+  const authUrl = buildAuthUrl({
+    clientId: credentials.clientId,
+    redirectUri,
+    state,
+    codeChallenge: challenge,
+    scopes: SCOPES,
+  });
+
+  deps.log('Open this URL in any browser, approve access, then copy the URL you land on:\n');
+  deps.log(authUrl + '\n');
+
+  const answer = await deps.promptForRedirectUrl('Paste the redirect URL (or just the code): ');
+  const code = extractCode(answer);
+  if (!code) {
+    throw new YtStatsError('Could not find an authorization code in that input.', {
+      code: ERROR_CODES.AUTH_FAILED,
+      hint: 'Paste the full URL from the address bar, including the ?code=... part.',
+    });
+  }
+  return { code, redirectUri };
+}
+
+function extractCode(input) {
+  const text = String(input ?? '').trim();
+  if (!text) return null;
+  try {
+    return new URL(text).searchParams.get('code');
+  } catch {
+    return text; // They pasted the bare code.
+  }
+}
+
+/** Revoke with Google (best effort) and forget the account locally. */
+export async function logout({ account: selector, all = false, forgetCredentials = false, env, cwd, deps: injected } = {}) {
+  const deps = { ...defaultDeps(), ...injected };
+  const accounts = all ? listAccounts() : [loadAccount(selector)].filter(Boolean);
+
+  if (accounts.length === 0) {
+    if (forgetCredentials) clearCredentials();
+    return { loggedOut: false, revoked: false, accounts: [] };
+  }
+
+  let credentials = null;
+  try {
+    credentials = resolveCredentials({ env, cwd });
+  } catch {
+    // Without the client secret we cannot revoke, but we can still forget locally.
+  }
+
+  let revoked = false;
+  for (const summary of accounts) {
+    const full = loadAccount(summary.channelId);
+    if (credentials && full?.tokens) {
+      try {
+        const client = newClient(deps, credentials, 'http://127.0.0.1');
+        client.setCredentials(full.tokens);
+        await client.revokeToken(full.tokens.refresh_token || full.tokens.access_token);
+        revoked = true;
+      } catch {
+        // Offline or already-invalid token: local removal below is what matters.
+      }
+    }
+    removeAccount(summary.channelId);
+  }
+
+  if (all) clearAllAccounts();
+  if (forgetCredentials) clearCredentials();
+
+  return { loggedOut: true, revoked, accounts: accounts.map(a => a.channelId) };
+}