@ulisesgascon/openjs-cna-tools 0.0.0-stage → 1.0.0-alpha.1

package/lib/client.js

@@ -0,0 +1,244 @@
+// CnaClient — the transport layer for the OpenJS Foundation CNA API.
+//
+// The CNA API is a thin edge in front of a `workflow_dispatch`-backed GitHub
+// Actions workflow. POST /dispatch returns a Worker-minted correlation_id;
+// GET /runs/{id} polls the backing run and, once it completes, returns the
+// operation's structured result extracted from the job log.
+//
+// Two layers:
+//
+//   * High-level methods (`reserveCve`, `publishCve`, `getCve`, `listCves`,
+//     `updateCve`, `health`) dispatch, wait for completion, throw on failure,
+//     and return the operation result.
+//
+//   * Low-level methods (`dispatch`, `poll`, `waitForCompletion`) expose the
+//     three primitives for callers that want to bridge polling externally
+//     (UIs, queues, retries, custom progress reporting).
+//
+// The constructor is non-allocating — no network, no fs, no subprocess. Token
+// and base-url validation is deferred until the first operation (the
+// self-replacing-getter pattern from node-core-utils).
+
+import { createRequire } from 'node:module'
+import {
+  CnaAuthError,
+  CnaTimeoutError,
+  CnaOperationError
+} from './errors.js'
+
+const require = createRequire(import.meta.url)
+const pkg = require('../package.json')
+
+// Single identity string used as the User-Agent on every outbound HTTP
+// request AND as `cna.x_generator.engine` on every container we publish.
+// Pinning both to the same string means a downstream reader of a CVE
+// record can find the exact `openjs-cna-tools <version>` that produced
+// the call.
+export const USER_AGENT = `${pkg.name} ${pkg.version}`
+
+const DEFAULT_TIMEOUT_MS = 600_000 // 10 minutes; matches NCU's choice
+const DEFAULT_POLL_INTERVAL_MS = 5_000
+
+export class CnaClient {
+  constructor ({ token, baseUrl, timeoutMs, pollIntervalMs, fetch: fetchImpl } = {}) {
+    this._token = token
+    this._baseUrl = baseUrl
+    this._timeoutMs = timeoutMs ?? DEFAULT_TIMEOUT_MS
+    this._pollIntervalMs = pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS
+    // Injectable for tests; defaults to the runtime's global fetch.
+    this._fetch = fetchImpl ?? globalThis.fetch
+  }
+
+  // Lazy validation. Reading `client.token` once is the only time we check
+  // the configuration. Re-reads pay no cost; missing-token failures throw at
+  // the exact moment the caller is about to make a network call, which is
+  // also the moment the operator can act on the error.
+  get token () {
+    if (!this._token) {
+      throw new CnaAuthError(
+        'OPENJS_CNA_TOKEN is not configured. Run:\n' +
+        '  openjs-cna-experimental config set -x openjs_cna_token "<bucket>:<hex-secret>"\n' +
+        'or pass --token / set OPENJS_CNA_TOKEN in the environment.'
+      )
+    }
+    return this._token
+  }
+
+  get baseUrl () {
+    if (!this._baseUrl) {
+      throw new CnaAuthError(
+        'OPENJS_CNA_BASE_URL is not configured. Run:\n' +
+        '  openjs-cna-experimental config set openjs_cna_base_url "https://cna.openjsf.org"\n' +
+        'or pass --base-url / set OPENJS_CNA_BASE_URL in the environment.'
+      )
+    }
+    return this._baseUrl.replace(/\/$/, '')
+  }
+
+  _authHeaders () {
+    return {
+      Authorization: `Bearer ${this.token}`,
+      Accept: 'application/json',
+      'User-Agent': USER_AGENT
+    }
+  }
+
+  // Unauthenticated liveness probe. Useful for `openjs-cna-experimental health` and for
+  // catching base-url misconfiguration without burning a workflow dispatch.
+  async health () {
+    const res = await this._fetch(`${this.baseUrl}/health`, {
+      headers: { 'User-Agent': USER_AGENT }
+    })
+    if (!res.ok) {
+      throw new CnaOperationError(`Health check failed: ${res.status} ${res.statusText}`)
+    }
+    return res.json()
+  }
+
+  // Low-level: POST /dispatch. Returns { correlation_id, status } from the
+  // Worker. Throws CnaAuthError on 401 so the CLI can map to exit 2.
+  async dispatch (operation, inputs = {}) {
+    const res = await this._fetch(`${this.baseUrl}/dispatch`, {
+      method: 'POST',
+      headers: { ...this._authHeaders(), 'Content-Type': 'application/json' },
+      body: JSON.stringify({ operation, inputs })
+    })
+    if (res.status === 401) {
+      throw new CnaAuthError(
+        'The CNA API rejected the bearer token (401). Check that ' +
+        '`openjs_cna_token` matches the bucket your CNA coordinator provisioned.',
+        { status: 401 }
+      )
+    }
+    let body
+    try {
+      body = await res.json()
+    } catch (e) {
+      throw new CnaOperationError(
+        `Dispatch returned non-JSON response (${res.status}): ${e.message}`
+      )
+    }
+    if (body?.error) {
+      throw new CnaOperationError(`Dispatch failed (${operation}): ${body.error}`)
+    }
+    return body
+  }
+
+  // Low-level: GET /runs/{id}. Returns the run object, possibly with a
+  // `result` field when the workflow has completed successfully.
+  async poll (correlationId) {
+    const res = await this._fetch(`${this.baseUrl}/runs/${correlationId}`, {
+      headers: this._authHeaders()
+    })
+    if (res.status === 401) {
+      throw new CnaAuthError('CNA API rejected the bearer token (401)', { status: 401 })
+    }
+    // 502 run_result_unavailable: completed+success but the Worker could not
+    // extract the marker block. Surface as an operation error with the run
+    // metadata still attached so the CLI can suggest `openjs-cna-experimental runs <id>`.
+    if (res.status === 502) {
+      const body = await res.json().catch(() => ({}))
+      throw new CnaOperationError(
+        body?.message ?? `CNA API returned 502 for run ${correlationId}`,
+        {
+          correlationId,
+          runId: body?.run_id
+        }
+      )
+    }
+    return res.json()
+  }
+
+  // Poll until the run completes. Throws on timeout, on a non-success
+  // conclusion, or on AbortSignal cancellation. `onPoll` lets callers update
+  // a progress UI without owning the polling loop.
+  async waitForCompletion (correlationId, opts = {}) {
+    const {
+      timeoutMs = this._timeoutMs,
+      intervalMs = this._pollIntervalMs,
+      signal,
+      onPoll
+    } = opts
+    const deadline = Date.now() + timeoutMs
+    while (Date.now() < deadline) {
+      if (signal?.aborted) throw new DOMException('aborted', 'AbortError')
+      const run = await this.poll(correlationId)
+      if (typeof onPoll === 'function') onPoll(run)
+      if (run.status === 'completed') {
+        if (run.conclusion !== 'success') {
+          throw new CnaOperationError(
+            `Run ${correlationId} concluded with '${run.conclusion}'. ` +
+            'Forward correlation_id and run_id to your CNA coordinator for inspection.',
+            {
+              correlationId,
+              runId: run.run_id,
+              conclusion: run.conclusion,
+              result: run.result
+            }
+          )
+        }
+        return run
+      }
+      await new Promise(resolve => setTimeout(resolve, intervalMs))
+    }
+    throw new CnaTimeoutError(
+      `Run ${correlationId} did not complete within ${timeoutMs}ms`,
+      { correlationId, timeoutMs }
+    )
+  }
+
+  // Internal: dispatch + wait. Every high-level method funnels through here.
+  async _runAndWait (operation, inputs, opts) {
+    const dispatched = await this.dispatch(operation, inputs)
+    const run = await this.waitForCompletion(dispatched.correlation_id, opts)
+    return { ...run, correlationId: dispatched.correlation_id }
+  }
+
+  // ----- High-level operations -----
+
+  async reserveCve (opts = {}) {
+    const run = await this._runAndWait('reserve-cve', {}, opts)
+    const cveId = run.result?.cve_id
+    if (!cveId) {
+      throw new CnaOperationError(
+        'reserve-cve completed but no cve_id in the result. ' +
+        'Forward correlation_id and run_id to your CNA coordinator.',
+        {
+          correlationId: run.correlationId,
+          runId: run.run_id,
+          result: run.result
+        }
+      )
+    }
+    return { cveId, correlationId: run.correlationId, runId: run.run_id, run }
+  }
+
+  async publishCve (cveId, container, opts = {}) {
+    const run = await this._runAndWait('publish-cve', {
+      cve_id: cveId,
+      cnaContainer: container
+    }, opts)
+    return { correlationId: run.correlationId, runId: run.run_id, run, result: run.result }
+  }
+
+  async updateCve (cveId, container, opts = {}) {
+    const run = await this._runAndWait('update-cve', {
+      cve_id: cveId,
+      cnaContainer: container
+    }, opts)
+    return { correlationId: run.correlationId, runId: run.run_id, run, result: run.result }
+  }
+
+  async getCve (cveId, opts = {}) {
+    const run = await this._runAndWait('get-cve', { cve_id: cveId }, opts)
+    return run.result
+  }
+
+  async listCves (opts = {}) {
+    const run = await this._runAndWait('list-cve', {}, opts)
+    // Two acceptable result shapes:
+    //   * { cve_ids: [...] }  — what the workflow currently emits
+    //   * [ ... ]              — direct array, in case the API evolves
+    return run.result?.cve_ids ?? (Array.isArray(run.result) ? run.result : [])
+  }
+}

package/lib/component-utils.js

@@ -0,0 +1,74 @@
+// Shared bootstrap for CLI components.
+//
+// Every component runs the same opening sequence: parse argv (mixing global
+// flags with its own), resolve credentials, build a CLI + CnaClient. This
+// module factors that out so each component file in components/ can stay
+// at ~30 lines.
+
+import { parseArgs } from 'node:util'
+import { CLI } from './cli.js'
+import { CnaClient } from './client.js'
+import { resolveCredentials } from './auth.js'
+
+const GLOBAL_OPTIONS = {
+  token: { type: 'string' },
+  'base-url': { type: 'string' },
+  timeout: { type: 'string' },
+  'poll-interval': { type: 'string' },
+  json: { type: 'boolean' },
+  quiet: { type: 'boolean' },
+  yes: { type: 'boolean', short: 'y' },
+  'no-color': { type: 'boolean' },
+  help: { type: 'boolean', short: 'h' }
+}
+
+export function parseComponentArgs (argv, componentOptions = {}, { allowPositionals = false } = {}) {
+  const options = { ...GLOBAL_OPTIONS, ...componentOptions }
+  let parsed
+  try {
+    parsed = parseArgs({ args: argv, options, allowPositionals })
+  } catch (e) {
+    process.stderr.write(`✖ ${e.message}\n`)
+    process.exit(64) // EX_USAGE
+  }
+  return parsed
+}
+
+export function buildCli ({ values } = { values: {} }) {
+  return new CLI(process.stderr, {
+    color: values['no-color'] ? false : undefined,
+    assumeYes: values.yes || process.env.OPENJS_CNA_YES === '1'
+  })
+}
+
+export function buildClient ({ values } = { values: {} }) {
+  const creds = resolveCredentials({
+    overrides: {
+      token: values.token,
+      baseUrl: values['base-url']
+    }
+  })
+  return new CnaClient({
+    token: creds.token,
+    baseUrl: creds.baseUrl,
+    timeoutMs: values.timeout ? Number(values.timeout) * 1000 : undefined,
+    pollIntervalMs: values['poll-interval'] ? Number(values['poll-interval']) * 1000 : undefined
+  })
+}
+
+// Convenience: read a file or stdin to text. Used by publish/update/review/
+// convert when -f is omitted.
+export async function readFileOrStdin (filePath) {
+  const fs = await import('node:fs/promises')
+  if (filePath && filePath !== '-') {
+    return fs.readFile(filePath, 'utf8')
+  }
+  // Read all of stdin.
+  return new Promise((resolve, reject) => {
+    let data = ''
+    process.stdin.setEncoding('utf8')
+    process.stdin.on('data', (chunk) => { data += chunk })
+    process.stdin.on('end', () => resolve(data))
+    process.stdin.on('error', reject)
+  })
+}

package/lib/config.js

@@ -0,0 +1,121 @@
+// Config layering for openjs-cna-tools.
+//
+// Precedence (highest → lowest):
+//   1. CLI flag (resolved by each component; not in scope here)
+//   2. Environment (OPENJS_CNA_TOKEN, OPENJS_CNA_BASE_URL, …)
+//   3. Project config: ./.openjs-cna.json in CWD
+//   4. Global config:  ~/.config/openjs-cna/config.json (XDG-friendly)
+//
+// Encryption-at-rest for secrets is on the roadmap (matches NCU's `-x` flag
+// shape via a `gpg` subprocess — no JS dep). Until that lands, secrets are
+// stored as plaintext and `set -x` is a no-op with a warning. The merged
+// config still uses property-descriptor merging so the encrypted-getter
+// pattern can drop in later without a breaking change to callers.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+
+const ENV_PREFIX = 'OPENJS_CNA_'
+
+const ENV_TO_KEY = {
+  OPENJS_CNA_TOKEN: 'openjs_cna_token',
+  OPENJS_CNA_BASE_URL: 'openjs_cna_base_url'
+}
+
+export function globalConfigPath () {
+  const xdg = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config')
+  return path.join(xdg, 'openjs-cna-experimental', 'config.json')
+}
+
+export function projectConfigPath (cwd = process.cwd()) {
+  return path.join(cwd, '.openjs-cna.json')
+}
+
+function safeReadJson (filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8')
+    return JSON.parse(raw)
+  } catch {
+    return {}
+  }
+}
+
+function envOverrides () {
+  const out = {}
+  for (const [envName, key] of Object.entries(ENV_TO_KEY)) {
+    if (process.env[envName] != null) out[key] = process.env[envName]
+  }
+  // Pass-through for any future OPENJS_CNA_* env vars we haven't mapped yet.
+  for (const [name, value] of Object.entries(process.env)) {
+    if (!name.startsWith(ENV_PREFIX)) continue
+    if (ENV_TO_KEY[name]) continue
+    const key = name.slice(ENV_PREFIX.length).toLowerCase()
+    out[key] = value
+  }
+  return out
+}
+
+// Merge configs using property descriptors so future encrypted-getter
+// properties survive the merge without being prematurely evaluated. Today
+// every value is a plain string; this is a no-op cost paid for future-
+// proofing.
+function mergeWithDescriptors (...sources) {
+  const out = Object.create(null)
+  for (const source of sources) {
+    if (!source) continue
+    Object.defineProperties(out, Object.getOwnPropertyDescriptors(source))
+  }
+  return out
+}
+
+export function getMergedConfig ({ cwd } = {}) {
+  const global = safeReadJson(globalConfigPath())
+  const project = safeReadJson(projectConfigPath(cwd))
+  const env = envOverrides()
+  return mergeWithDescriptors(global, project, env)
+}
+
+function ensureDir (filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+}
+
+export function setConfigValue (key, value, { scope = 'global', cwd } = {}) {
+  const target = scope === 'project' ? projectConfigPath(cwd) : globalConfigPath()
+  const current = safeReadJson(target)
+  current[key] = value
+  ensureDir(target)
+  fs.writeFileSync(target, JSON.stringify(current, null, 2) + '\n', { mode: 0o600 })
+  return target
+}
+
+export function getConfigValue (key, opts = {}) {
+  const merged = getMergedConfig(opts)
+  return merged[key]
+}
+
+export function deleteConfigValue (key, { scope = 'global', cwd } = {}) {
+  const target = scope === 'project' ? projectConfigPath(cwd) : globalConfigPath()
+  const current = safeReadJson(target)
+  if (!(key in current)) return false
+  delete current[key]
+  ensureDir(target)
+  fs.writeFileSync(target, JSON.stringify(current, null, 2) + '\n', { mode: 0o600 })
+  return true
+}
+
+// Returns a redacted view of the merged config: secret-looking keys
+// (anything containing 'token' or 'secret') are replaced with a fixed
+// placeholder so `openjs-cna-experimental config list` can be piped without leaking.
+export function listConfig (opts = {}) {
+  const merged = getMergedConfig(opts)
+  const out = {}
+  for (const [key, value] of Object.entries(merged)) {
+    if (/token|secret|password/i.test(key)) {
+      out[key] = '<redacted>'
+    } else {
+      out[key] = value
+    }
+  }
+  return out
+}