ravensight-playtest 0.1.0

package/src/api/index.js

@@ -0,0 +1,107 @@
+/**
+ * The runner facing interface. See ./README.md for the contract.
+ *
+ * This module is the package's public entry point and the only thing
+ * `src/run/*` and `src/run/drivers/*` may import from outside their own
+ * directory. Everything else under `src/` is implementation detail. Adding an
+ * export here is a deliberate act; reaching past it is not.
+ */
+
+export { createClient } from './client.js';
+export { ApiError, isRetryable, codeRetryLimit, parseRetryAfter } from './errors.js';
+export { CliError, ExitCode, authError, environmentError } from '../errors.js';
+export { resolveApiUrl, apiHost, paths, RUN_FILES, JOB_FILES, DEFAULT_API_URL } from '../paths.js';
+export {
+  resolveToken,
+  looksLikeCliToken,
+  looksLikeIngestKey,
+  handleUnauthorized,
+  withAuthHandling,
+  TOKEN_PREFIX
+} from '../auth/session.js';
+export { loadConfig, requireConfig, saveConfig, defaultConfig, resolveGameId } from '../config.js';
+export { packs } from '../packs/index.js';
+export {
+  uploadRunDir,
+  finalizeRun,
+  planRunDir,
+  walkRunDir,
+  putFile,
+  taggingHeader,
+  unverifiedPaths
+} from '../upload/index.js';
+export {
+  contentTypeFor,
+  isAllowedPath,
+  JOB_UPLOAD_PATHS,
+  RETENTION_TAGGED_PATHS,
+  VIDEO_PATHS,
+  TRANSCRIPT_PATH,
+  MAX_FILES_PER_RUN,
+  MAX_RUN_BYTES,
+  MAX_VIDEO_BYTES
+} from '../upload/allowlist.js';
+export { readQueue, pending as pendingUploads, STATUS as UPLOAD_STATUS } from '../upload/queue.js';
+export {
+  readState,
+  writeState,
+  updateState,
+  listStates,
+  newState,
+  stateFileFor,
+  STATE_VERSION
+} from '../state/index.js';
+export { ui } from '../ui/index.js';
+export {
+  MODULES,
+  DRIVERS,
+  JOB_STATES,
+  JOB_TERMINAL_STATES,
+  RUN_STATES,
+  RUN_TERMINAL_STATES,
+  RUN_TRANSITIONS,
+  isJobTerminal,
+  isRunTerminal,
+  canTransitionRun
+} from '../states.js';
+export { dashboardUrl, gameLink, jobLink, reviewLink, briefLink, trustLink, openInBrowser } from '../dashboard.js';
+export { inspectGodot } from '../godot.js';
+export { recommendConcurrency, freeBytes, probe } from '../detect.js';
+export { CLI_VERSION, CLIENT_NAME, compareVersions } from '../version.js';
+export { sha256, sha256File, readJson, writeJson, writeFileAtomic, stableStringify } from '../fsutil.js';
+
+import { createClient } from './client.js';
+import { resolveApiUrl } from '../paths.js';
+import { resolveToken } from '../auth/session.js';
+import { loadConfig } from '../config.js';
+
+/**
+ * Resolve everything a command needs in one call: the API URL, the credential,
+ * the repo's config, and a client built from them.
+ *
+ * Every command starts this way, so the order of precedence (flag, then env,
+ * then config, then default) exists once rather than nine times.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.apiUrl]
+ * @param {string} [options.repoRoot]
+ * @param {boolean} [options.requireAuth] - throw when there is no credential
+ * @param {Object} [options.clientOptions] - passed through to createClient
+ * @returns {Promise<{api: Object, apiUrl: string, token: string|null,
+ *   tokenSource: string|null, host: string, config: Object|null, repoRoot: string}>}
+ */
+export async function createContext(options = {}) {
+  const apiUrl = options.apiUrl || resolveApiUrl();
+  const { token, source, host } = await resolveToken({ apiUrl, required: options.requireAuth });
+  const config = await loadConfig({ repoRoot: options.repoRoot });
+  const api = createClient({ apiUrl, token, ...(options.clientOptions || {}) });
+  return {
+    api,
+    apiUrl,
+    token,
+    tokenSource: source,
+    host,
+    config,
+    repoRoot: options.repoRoot || process.cwd()
+  };
+}

package/src/auth/deviceCode.js

@@ -0,0 +1,79 @@
+import { ApiError } from '../api/errors.js';
+import { authError } from '../errors.js';
+
+const MIN_INTERVAL_SECONDS = 1;
+const MAX_INTERVAL_SECONDS = 60;
+/** How much the interval grows when the server says slow_down. */
+const SLOW_DOWN_BUMP_SECONDS = 5;
+
+/**
+ * Poll `POST /playtest/cli/token` until the person approves, denies, or the
+ * device code expires.
+ *
+ * The four non-200 answers mean four different things and the loop treats them
+ * differently, which is the whole reason the server bothers to distinguish
+ * them:
+ *
+ * - 428 `authorization_pending`: nobody has acted yet. Wait and ask again.
+ * - 429 `slow_down`: we polled sooner than `interval`. Wait longer, and grow
+ *   the interval so it does not happen again. This is NOT a generic rate
+ *   limit retry, so it is handled here rather than inside the HTTP layer.
+ * - 400 `expired_token`: the code is gone, for any reason. Stop.
+ * - 403 `access_denied`: a person said no. Stop, and say so differently.
+ *
+ * @param {Object} options
+ * @param {import('../api/client.js').createClient} options.api
+ * @param {string} options.deviceCode
+ * @param {number} [options.intervalSeconds] - the server's suggested interval
+ * @param {number} [options.expiresInSeconds]
+ * @param {(state: {waited: number}) => void} [options.onPoll]
+ * @param {(ms: number) => Promise<void>} [options.sleep]
+ * @param {() => number} [options.now]
+ * @returns {Promise<{token: string, games: Array, scopes: Array, expires_at: string}>}
+ */
+export async function pollForToken(options) {
+  const {
+    api,
+    deviceCode,
+    intervalSeconds = 5,
+    expiresInSeconds = 600,
+    onPoll,
+    sleep = ms => new Promise(resolve => setTimeout(resolve, ms)),
+    now = () => Date.now()
+  } = options;
+
+  let interval = Math.min(Math.max(intervalSeconds, MIN_INTERVAL_SECONDS), MAX_INTERVAL_SECONDS);
+  const startedAt = now();
+  const deadline = startedAt + expiresInSeconds * 1000;
+
+  for (;;) {
+    await sleep(interval * 1000);
+    if (onPoll) onPoll({ waited: Math.round((now() - startedAt) / 1000) });
+
+    try {
+      return await api.cli.pollToken(deviceCode);
+    } catch (error) {
+      if (!(error instanceof ApiError)) throw error;
+
+      if (error.code === 'authorization_pending') {
+        // Keep waiting. The deadline below is what ends the loop.
+      } else if (error.code === 'slow_down') {
+        interval = Math.min(interval + SLOW_DOWN_BUMP_SECONDS, MAX_INTERVAL_SECONDS);
+      } else if (error.code === 'access_denied') {
+        throw authError('That login was denied on the dashboard.');
+      } else if (error.code === 'expired_token') {
+        throw authError('That login expired before it was approved.', 'Run login again.');
+      } else if (error.isNetwork) {
+        // A dropped connection mid login is not a failed login. Back off once
+        // and keep polling until the code itself expires.
+        interval = Math.min(interval + SLOW_DOWN_BUMP_SECONDS, MAX_INTERVAL_SECONDS);
+      } else {
+        throw error;
+      }
+    }
+
+    if (now() >= deadline) {
+      throw authError('That login expired before it was approved.', 'Run login again.');
+    }
+  }
+}

package/src/auth/keychain.js

@@ -0,0 +1,159 @@
+import { mkdir } from 'node:fs/promises';
+import { unlink } from 'node:fs/promises';
+import { paths } from '../paths.js';
+import { readJson, writeJson } from '../fsutil.js';
+
+export const KEYCHAIN_SERVICE = 'ravensight-playtest';
+const FILE_MODE = 0o600;
+
+let keytarModule;
+let keytarTried = false;
+
+/**
+ * `keytar` is a native module, and every realistic reason it is missing is a
+ * reason the CLI still has to work: it is an optional dependency whose install
+ * script may not have run, a headless Linux box with no libsecret, or a CI
+ * container. So it is required lazily, once, inside a try, and a failure means
+ * "use the file backend" rather than "crash".
+ *
+ * @returns {Promise<object|null>}
+ */
+async function keytar() {
+  if (keytarTried) return keytarModule || null;
+  keytarTried = true;
+  try {
+    const mod = await import('keytar');
+    const candidate = mod.default || mod;
+    // An import that resolves but has no getPassword is a broken build, not a
+    // working backend: treat it exactly like an absent module.
+    keytarModule = typeof candidate.getPassword === 'function' ? candidate : null;
+  } catch {
+    keytarModule = null;
+  }
+  return keytarModule;
+}
+
+/** Test seam: forget the cached probe so a stub can be installed. */
+export function resetKeychainProbe(stub) {
+  keytarTried = stub !== undefined;
+  keytarModule = stub === undefined ? undefined : stub;
+}
+
+/**
+ * Which backend is in use, for `check` to report. The OS keychain when keytar
+ * loaded, otherwise the 0600 file, and `env` is not a backend at all: it is a
+ * credential this process was handed and will not store.
+ * @returns {Promise<'keychain'|'file'>}
+ */
+export async function backendName() {
+  return (await keytar()) ? 'keychain' : 'file';
+}
+
+async function fileStore() {
+  const value = await readJson(paths.credentialsFile(), {});
+  return value && typeof value === 'object' ? value : {};
+}
+
+async function writeFileStore(store) {
+  await mkdir(paths.userDir(), { recursive: true, mode: 0o700 });
+  await writeJson(paths.credentialsFile(), store, { mode: FILE_MODE });
+}
+
+/**
+ * The stored token for one API host, and which backend answered.
+ *
+ * The backend is reported rather than inferred, because the two are genuinely
+ * independent: `backendName()` says which store this machine WOULD use, and
+ * this says which one the token actually came out of. A token written to the
+ * file when the keychain was locked, and read back later when it is not, comes
+ * from the file while the backend is the keychain, and `check` should say the
+ * true thing.
+ *
+ * Hosts are separate accounts: a token minted against a staging server must
+ * never be sent to production.
+ *
+ * @param {string} host
+ * @returns {Promise<{token: string|null, backend: 'keychain'|'file'|null}>}
+ */
+export async function readStoredToken(host) {
+  const kt = await keytar();
+  if (kt) {
+    try {
+      const found = await kt.getPassword(KEYCHAIN_SERVICE, host);
+      if (found) return { token: found, backend: 'keychain' };
+    } catch {
+      // A locked or unavailable keychain falls through to the file, rather than
+      // failing a command that could have worked.
+    }
+  }
+  const store = await fileStore();
+  const entry = store[host];
+  return typeof entry === 'string'
+    ? { token: entry, backend: 'file' }
+    : { token: null, backend: null };
+}
+
+/**
+ * The stored token for one API host, or null.
+ * @param {string} host
+ * @returns {Promise<string|null>}
+ */
+export async function getStoredToken(host) {
+  return (await readStoredToken(host)).token;
+}
+
+/**
+ * Store a token for one host.
+ * @param {string} host
+ * @param {string} token
+ * @returns {Promise<{backend: 'keychain'|'file'}>}
+ */
+export async function setStoredToken(host, token) {
+  const kt = await keytar();
+  if (kt) {
+    try {
+      await kt.setPassword(KEYCHAIN_SERVICE, host, token);
+      return { backend: 'keychain' };
+    } catch {
+      // Fall through: a token we cannot store is a login the developer has to
+      // repeat, which is worse than a file with 0600 on it.
+    }
+  }
+  const store = await fileStore();
+  store[host] = token;
+  await writeFileStore(store);
+  return { backend: 'file' };
+}
+
+/**
+ * Forget the token for one host. Answers whether anything was there, so
+ * `logout` can tell "revoked and cleared" from "nothing to clear".
+ * @param {string} host
+ * @returns {Promise<boolean>}
+ */
+export async function deleteStoredToken(host) {
+  let removed = false;
+  const kt = await keytar();
+  if (kt) {
+    try {
+      removed = Boolean(await kt.deletePassword(KEYCHAIN_SERVICE, host));
+    } catch {
+      removed = false;
+    }
+  }
+  const store = await fileStore();
+  if (Object.prototype.hasOwnProperty.call(store, host)) {
+    delete store[host];
+    if (Object.keys(store).length === 0) {
+      try {
+        await unlink(paths.credentialsFile());
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+      }
+    } else {
+      await writeFileStore(store);
+    }
+    removed = true;
+  }
+  return removed;
+}

package/src/auth/session.js

@@ -0,0 +1,128 @@
+import { apiHost, resolveApiUrl } from '../paths.js';
+import { authError } from '../errors.js';
+import { ApiError } from '../api/errors.js';
+import { deleteStoredToken, readStoredToken } from './keychain.js';
+import { ui } from '../ui/index.js';
+
+export const TOKEN_PREFIX = 'gt_cli_';
+
+/**
+ * Find the credential to use, and say where it came from.
+ *
+ * `RAVENSIGHT_TOKEN` wins over the keychain, which is what makes CI work: a
+ * runner in a container has no keychain, and an explicit env var must not be
+ * quietly overridden by whatever happens to be stored on a developer machine
+ * that shares a home directory with it.
+ *
+ * `source` is the real origin, not a label: `'env'`, or `'keychain'` or
+ * `'file'` depending on which store actually answered. Calling a token from the
+ * fallback file a keychain token would make `check`'s own report wrong, which is
+ * the one place a developer looks to find out why a credential is not being
+ * picked up.
+ *
+ * @param {{apiUrl?: string, required?: boolean}} [options]
+ * @returns {Promise<{token: string|null, source: 'env'|'keychain'|'file'|null, host: string}>}
+ */
+export async function resolveToken(options = {}) {
+  const apiUrl = options.apiUrl || resolveApiUrl();
+  const host = apiHost(apiUrl);
+
+  const fromEnv = process.env.RAVENSIGHT_TOKEN;
+  if (fromEnv && fromEnv.trim()) {
+    return { token: fromEnv.trim(), source: 'env', host };
+  }
+
+  const stored = await readStoredToken(host);
+  if (stored.token) return { token: stored.token, source: stored.backend, host };
+
+  if (options.required) {
+    throw authError(
+      `Not logged in to ${host}.`,
+      'Run ravensight-playtest login, or set RAVENSIGHT_TOKEN for CI.'
+    );
+  }
+  return { token: null, source: null, host };
+}
+
+/**
+ * Whether a string looks like a CLI token. Only ever used to warn: the server
+ * decides what a valid credential is, and a client side shape check that
+ * rejected a token the server would have accepted would be a bug that no
+ * amount of logging in could fix.
+ * @param {string|null|undefined} token
+ * @returns {boolean}
+ */
+export function looksLikeCliToken(token) {
+  return typeof token === 'string' && token.startsWith(TOKEN_PREFIX);
+}
+
+/**
+ * Whether a string looks like an ingest key. Worth its own check because
+ * pasting one in is a mistake people actually make, and the server answers 403
+ * `ingest_key_not_allowed` rather than 401, which reads like a permissions
+ * problem instead of "wrong kind of key".
+ * @param {string|null|undefined} token
+ * @returns {boolean}
+ */
+export function looksLikeIngestKey(token) {
+  return typeof token === 'string' && token.startsWith('gt_live_');
+}
+
+/**
+ * What to do when the server refuses the credential.
+ *
+ * A 401 means the token this machine holds is no longer a credential: revoked
+ * from the dashboard, expired past its sliding TTL, or minted against another
+ * deployment. Keeping it means every later command fails the same way, and the
+ * developer has to work out that `logout` is the fix for a problem that never
+ * said "log out". So a stored token is deleted here, and the message says it
+ * was, which turns an unexplained 401 into one obvious next step.
+ *
+ * A token from `RAVENSIGHT_TOKEN` is NEVER deleted, for the same reason `logout`
+ * leaves it alone: it is the caller's, it is probably a CI secret shared with
+ * other jobs, and this process has no business deciding it is finished with. It
+ * is only reported.
+ *
+ * Every command funnels its API work through this, so the clearing happens in
+ * one place rather than in nine catch blocks that could each forget.
+ *
+ * @param {{tokenSource?: string, host?: string, apiUrl?: string}} context
+ * @param {unknown} error
+ * @returns {Promise<Error>} the error to throw, unchanged when it was not a 401
+ */
+export async function handleUnauthorized(context, error) {
+  if (!(error instanceof ApiError) || error.status !== 401) return error;
+
+  const source = context && context.tokenSource;
+  const host = (context && context.host) || apiHost(context && context.apiUrl);
+
+  if (source === 'env') {
+    return authError(
+      `${host} refused the token in RAVENSIGHT_TOKEN.`,
+      'Mint a new CLI token and update that secret. The variable was left alone.'
+    );
+  }
+
+  const cleared = await deleteStoredToken(host);
+  if (cleared) ui.warn(`${host} refused this machine's token, so it has been cleared.`);
+  return authError(
+    cleared ? `${host} no longer accepts the stored token.` : `${host} refused the credential.`,
+    'Run ravensight-playtest login.'
+  );
+}
+
+/**
+ * Run API work with the 401 handling above applied. The shape every command
+ * uses, so no command has to remember the catch.
+ *
+ * @param {Object} context
+ * @param {Function} fn
+ * @returns {Promise<unknown>}
+ */
+export async function withAuthHandling(context, fn) {
+  try {
+    return await fn();
+  } catch (error) {
+    throw await handleUnauthorized(context, error);
+  }
+}