actions-warden 0.1.0

package/src/lib/parser.js

@@ -0,0 +1,279 @@
+/**
+ * YAML workflow parser.
+ *
+ * Parses GitHub Actions workflow files into a structure annotated with line
+ * numbers for every job, step, and `uses:` reference. Line numbers refer to
+ * 1-indexed positions in the source.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { parseDocument, isMap, isSeq, isPair, isScalar } from 'yaml';
+
+/**
+ * @typedef {object} ActionRef
+ * @property {string} raw            - e.g. `actions/checkout@v3` or `./local`
+ * @property {string|null} owner
+ * @property {string|null} repo
+ * @property {string|null} subpath   - reusable-workflow sub-path
+ * @property {string|null} ref       - tag, branch, or SHA after `@`
+ * @property {'external'|'reusable-workflow'|'local'|'docker'|'unknown'} kind
+ * @property {number} line
+ */
+
+/**
+ * @typedef {object} StepNode
+ * @property {string|null} name
+ * @property {string|null} id
+ * @property {ActionRef|null} uses
+ * @property {string|null} run
+ * @property {object|null} env
+ * @property {object|null} with_
+ * @property {number} line
+ */
+
+/**
+ * @typedef {object} JobNode
+ * @property {string} name
+ * @property {object|null} permissions
+ * @property {string|null} runsOn
+ * @property {object|null} env
+ * @property {StepNode[]} steps
+ * @property {number} line
+ */
+
+/**
+ * @typedef {object} WorkflowDoc
+ * @property {string} path
+ * @property {string} source
+ * @property {string|null} name
+ * @property {unknown} on
+ * @property {object|null} permissions
+ * @property {object|null} env
+ * @property {JobNode[]} jobs
+ * @property {object} raw         - the parsed plain object (for rules to query)
+ */
+
+/**
+ * @param {string} raw e.g. `actions/checkout@v3` or `./local`
+ * @param {number} line
+ * @returns {ActionRef}
+ */
+export function parseActionRef(raw, line) {
+  /** @type {ActionRef} */
+  const base = {
+    raw,
+    owner: null,
+    repo: null,
+    subpath: null,
+    ref: null,
+    kind: 'unknown',
+    line,
+  };
+  if (typeof raw !== 'string' || raw.length === 0) return base;
+  if (raw.startsWith('./') || raw.startsWith('../')) {
+    return { ...base, kind: 'local' };
+  }
+  if (raw.startsWith('docker://')) {
+    return { ...base, kind: 'docker' };
+  }
+  const atIndex = raw.lastIndexOf('@');
+  if (atIndex <= 0) return base;
+  const left = raw.slice(0, atIndex);
+  const ref = raw.slice(atIndex + 1);
+  const parts = left.split('/');
+  if (parts.length < 2) return base;
+  const owner = parts[0];
+  const repo = parts[1];
+  const rest = parts.slice(2).join('/');
+  const kind = /\.(yml|yaml)$/.test(rest) ? 'reusable-workflow' : 'external';
+  return { ...base, owner, repo, subpath: rest || null, ref, kind };
+}
+
+/**
+ * @param {unknown} node
+ * @returns {number}
+ */
+function lineOf(node) {
+  if (node && typeof node === 'object' && 'range' in node && Array.isArray(node.range)) {
+    // We won't use this path; line is computed externally from the document.
+  }
+  return 0;
+}
+
+/**
+ * Find the 1-based line of a Pair/Scalar node within the YAML document.
+ *
+ * @param {string} source
+ * @param {{range?: number[]}} node
+ * @returns {number}
+ */
+function lineFromRange(source, node) {
+  if (!node || !node.range || node.range.length === 0) return 0;
+  const offset = node.range[0];
+  let line = 1;
+  for (let i = 0; i < offset && i < source.length; i += 1) {
+    if (source.charCodeAt(i) === 10) line += 1;
+  }
+  return line;
+}
+
+/**
+ * Read a Pair value into a JS scalar where possible.
+ *
+ * @param {unknown} node
+ */
+function toJs(node) {
+  if (node == null) return null;
+  if (typeof node !== 'object') return node;
+  if ('toJSON' in node && typeof node.toJSON === 'function') return node.toJSON();
+  return node;
+}
+
+/**
+ * Locate a child Pair by key within a YAMLMap.
+ *
+ * @param {object} map  - yaml YAMLMap node
+ * @param {string} key
+ * @returns {object|null}
+ */
+function findPair(map, key) {
+  if (!map || !isMap(map)) return null;
+  for (const item of map.items) {
+    if (isPair(item) && isScalar(item.key) && item.key.value === key) {
+      return item;
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string} source
+ * @param {object} doc - yaml Document
+ * @returns {JobNode[]}
+ */
+function extractJobs(source, doc) {
+  /** @type {JobNode[]} */
+  const jobs = [];
+  const jobsPair = findPair(doc.contents, 'jobs');
+  if (!jobsPair || !isMap(jobsPair.value)) return jobs;
+
+  for (const jobPair of jobsPair.value.items) {
+    if (!isPair(jobPair) || !isScalar(jobPair.key)) continue;
+    const jobName = String(jobPair.key.value);
+    const jobNode = jobPair.value;
+    const jobLine = lineFromRange(source, jobPair.key);
+
+    /** @type {JobNode} */
+    const job = {
+      name: jobName,
+      permissions: null,
+      runsOn: null,
+      env: null,
+      steps: [],
+      line: jobLine,
+    };
+
+    if (isMap(jobNode)) {
+      const perms = findPair(jobNode, 'permissions');
+      if (perms) job.permissions = toJs(perms.value);
+      const runsOn = findPair(jobNode, 'runs-on');
+      if (runsOn) job.runsOn = toJs(runsOn.value);
+      const env = findPair(jobNode, 'env');
+      if (env) job.env = toJs(env.value);
+
+      const stepsPair = findPair(jobNode, 'steps');
+      if (stepsPair && isSeq(stepsPair.value)) {
+        for (const stepNode of stepsPair.value.items) {
+          if (!isMap(stepNode)) continue;
+          const usesPair = findPair(stepNode, 'uses');
+          const runPair = findPair(stepNode, 'run');
+          const namePair = findPair(stepNode, 'name');
+          const idPair = findPair(stepNode, 'id');
+          const envPair = findPair(stepNode, 'env');
+          const withPair = findPair(stepNode, 'with');
+
+          const stepLine = lineFromRange(source, stepNode);
+          /** @type {StepNode} */
+          const step = {
+            name: namePair && isScalar(namePair.value) ? String(namePair.value.value) : null,
+            id: idPair && isScalar(idPair.value) ? String(idPair.value.value) : null,
+            uses: null,
+            run: runPair && isScalar(runPair.value) ? String(runPair.value.value) : null,
+            env: envPair ? toJs(envPair.value) : null,
+            with_: withPair ? toJs(withPair.value) : null,
+            line: stepLine,
+          };
+          if (usesPair && isScalar(usesPair.value)) {
+            const usesLine = lineFromRange(source, usesPair.value);
+            step.uses = parseActionRef(String(usesPair.value.value), usesLine);
+          }
+          job.steps.push(step);
+        }
+      }
+    }
+    jobs.push(job);
+  }
+  return jobs;
+}
+
+/**
+ * Parse a workflow YAML source into a {@link WorkflowDoc}.
+ *
+ * @param {string} source
+ * @param {string} path
+ * @returns {WorkflowDoc}
+ */
+export function parseWorkflowSource(source, path) {
+  const doc = parseDocument(source, { keepSourceTokens: true });
+  if (doc.errors && doc.errors.length > 0) {
+    const first = doc.errors[0];
+    throw new Error(`yaml parse error in ${path}: ${first.message}`);
+  }
+  /** @type {WorkflowDoc} */
+  const result = {
+    path,
+    source,
+    name: null,
+    on: null,
+    permissions: null,
+    env: null,
+    jobs: [],
+    raw: doc.toJS() ?? {},
+  };
+  if (!doc.contents || !isMap(doc.contents)) return result;
+  const namePair = findPair(doc.contents, 'name');
+  if (namePair && isScalar(namePair.value)) result.name = String(namePair.value.value);
+  const onPair = findPair(doc.contents, 'on');
+  if (onPair) result.on = toJs(onPair.value);
+  const permPair = findPair(doc.contents, 'permissions');
+  if (permPair) result.permissions = toJs(permPair.value);
+  const envPair = findPair(doc.contents, 'env');
+  if (envPair) result.env = toJs(envPair.value);
+  result.jobs = extractJobs(source, doc);
+  return result;
+}
+
+/**
+ * @param {string} path
+ * @returns {Promise<WorkflowDoc>}
+ */
+export async function parseWorkflowFile(path) {
+  const source = await readFile(path, 'utf8');
+  return parseWorkflowSource(source, path);
+}
+
+/**
+ * Iterate every action reference in a workflow.
+ *
+ * @param {WorkflowDoc} workflow
+ * @returns {Array<{ref: ActionRef, jobName: string, stepIndex: number}>}
+ */
+export function collectUses(workflow) {
+  const out = [];
+  for (const job of workflow.jobs) {
+    job.steps.forEach((step, i) => {
+      if (step.uses) out.push({ ref: step.uses, jobName: job.name, stepIndex: i });
+    });
+  }
+  return out;
+}

package/src/lib/paths.js

@@ -0,0 +1,99 @@
+/**
+ * Workflow file discovery with safe path handling.
+ */
+
+import { readdir, stat } from 'node:fs/promises';
+import { resolve, join, relative } from 'node:path';
+import picomatch from 'picomatch';
+
+/**
+ * Default workflow directory globs.
+ */
+export const DEFAULT_WORKFLOW_PATTERNS = [
+  '.github/workflows/*.yml',
+  '.github/workflows/*.yaml',
+];
+
+/**
+ * Reject path-traversal and absolute-escape attempts.
+ *
+ * @param {string} p
+ * @param {string} cwd
+ */
+function assertInside(p, cwd) {
+  const abs = resolve(cwd, p);
+  const rel = relative(cwd, abs);
+  if (rel.startsWith('..') || rel.includes('\0')) {
+    throw new Error(`path traversal rejected: ${p}`);
+  }
+  return abs;
+}
+
+/**
+ * Recursively list files under a directory.
+ *
+ * @param {string} dir
+ * @param {string[]} acc
+ * @returns {Promise<string[]>}
+ */
+async function walk(dir, acc = []) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith('.git') && entry.name !== '.github') continue;
+    if (entry.name === 'node_modules') continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await walk(full, acc);
+    } else if (entry.isFile()) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+/**
+ * Discover workflow files matching the given patterns (relative to cwd).
+ *
+ * @param {object} opts
+ * @param {string[]} [opts.patterns]
+ * @param {string} [opts.cwd]
+ * @returns {Promise<string[]>}
+ */
+export async function discoverWorkflows({ patterns = DEFAULT_WORKFLOW_PATTERNS, cwd = process.cwd() } = {}) {
+  for (const p of patterns) assertInside(p, cwd);
+  const matchers = patterns.map(p => picomatch(p, { dot: true }));
+  const all = await walk(cwd);
+  const out = [];
+  for (const file of all) {
+    const rel = relative(cwd, file);
+    if (matchers.some(m => m(rel))) out.push(file);
+  }
+  return out.sort();
+}
+
+/**
+ * Resolve a single workflow path argument. If it's a directory or glob,
+ * expand it; if a file, validate it exists.
+ *
+ * @param {string} input
+ * @param {string} [cwd]
+ * @returns {Promise<string[]>}
+ */
+export async function resolveWorkflowArg(input, cwd = process.cwd()) {
+  const abs = assertInside(input, cwd);
+  try {
+    const st = await stat(abs);
+    if (st.isDirectory()) {
+      const files = await walk(abs);
+      return files.filter(f => /\.ya?ml$/.test(f));
+    }
+    return [abs];
+  } catch {
+    return discoverWorkflows({ patterns: [input], cwd });
+  }
+}

package/src/lib/redact.js

@@ -0,0 +1,44 @@
+/**
+ * Secret redaction utility.
+ *
+ * Replaces values that look like tokens, credentials, or high-entropy strings
+ * with `<redacted>`. Conservative by design: prefers false positives over leaks.
+ */
+
+const TOKEN_PATTERNS = [
+  /ghp_[A-Za-z0-9]{30,}/g,
+  /ghs_[A-Za-z0-9]{30,}/g,
+  /gho_[A-Za-z0-9]{30,}/g,
+  /ghu_[A-Za-z0-9]{30,}/g,
+  /github_pat_[A-Za-z0-9_]{30,}/g,
+  /xox[abprs]-[A-Za-z0-9-]{10,}/g,
+  /AKIA[0-9A-Z]{16}/g,
+  /sk-[A-Za-z0-9]{20,}/g,
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+];
+
+const KV_TOKEN_KEYS = /\b(token|secret|password|api[_-]?key|auth[_-]?token|access[_-]?key|private[_-]?key)\s*[:=]\s*["']?([^"'\s,]+)/gi;
+
+/**
+ * Redacts sensitive substrings from a value.
+ *
+ * @param {unknown} input
+ * @returns {string}
+ */
+export function redact(input) {
+  if (input == null) return '';
+  let s = typeof input === 'string' ? input : String(input);
+  for (const re of TOKEN_PATTERNS) s = s.replace(re, '<redacted>');
+  s = s.replace(KV_TOKEN_KEYS, (_, key) => `${key}=<redacted>`);
+  return s;
+}
+
+/**
+ * Wraps console.error/log so any string-coerced argument is redacted first.
+ *
+ * @param {(...args: unknown[]) => void} fn
+ * @returns {(...args: unknown[]) => void}
+ */
+export function safeLogger(fn) {
+  return (...args) => fn(...args.map(a => (typeof a === 'string' ? redact(a) : a)));
+}

package/src/lib/resolver.js

@@ -0,0 +1,224 @@
+/**
+ * GitHub API version resolver.
+ *
+ * Resolves tags/branches to commit SHAs and looks up latest releases. Uses
+ * native fetch, with exponential backoff on rate-limit (HTTP 403 + ratelimit
+ * remaining 0) and 5xx responses. Caches successful responses to disk.
+ */
+
+import semver from 'semver';
+import { readCache, writeCache } from './cache.js';
+import { redact } from './redact.js';
+
+const API = 'https://api.github.com';
+
+/**
+ * Resolve the API token. Precedence: explicit param > GITHUB_TOKEN > GH_TOKEN.
+ *
+ * @param {string|undefined} explicit
+ * @returns {string|undefined}
+ */
+export function resolveToken(explicit) {
+  if (explicit && explicit.length > 0) return explicit;
+  if (process.env.GITHUB_TOKEN) return process.env.GITHUB_TOKEN;
+  if (process.env.GH_TOKEN) return process.env.GH_TOKEN;
+  return undefined;
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.url
+ * @param {string} [opts.token]
+ * @param {number} [opts.retries]
+ * @param {string} [opts.cwd]
+ * @param {boolean} [opts.useCache]
+ * @returns {Promise<{status: number, body: unknown}>}
+ */
+export async function ghFetch({ url, token, retries = 3, cwd = process.cwd(), useCache = true }) {
+  if (useCache) {
+    const cached = await readCache({ key: url, cwd });
+    if (cached !== undefined) return { status: 200, body: cached };
+  }
+
+  const headers = {
+    accept: 'application/vnd.github+json',
+    'user-agent': 'actions-warden',
+    'x-github-api-version': '2022-11-28',
+  };
+  if (token) headers.authorization = `Bearer ${token}`;
+
+  let attempt = 0;
+  for (;;) {
+    let response;
+    try {
+      response = await fetch(url, { headers });
+    } catch (err) {
+      if (attempt >= retries) throw new Error(`github fetch failed: ${redact(String(err))}`);
+      await sleep(backoff(attempt));
+      attempt += 1;
+      continue;
+    }
+    const remaining = response.headers.get('x-ratelimit-remaining');
+    if ((response.status === 403 && remaining === '0') || response.status === 429) {
+      const reset = Number(response.headers.get('x-ratelimit-reset') ?? 0) * 1000;
+      const wait = Math.max(reset - Date.now(), backoff(attempt));
+      if (attempt >= retries) {
+        throw new Error('github rate limit exhausted');
+      }
+      await sleep(Math.min(wait, 30_000));
+      attempt += 1;
+      continue;
+    }
+    if (response.status >= 500 && attempt < retries) {
+      await sleep(backoff(attempt));
+      attempt += 1;
+      continue;
+    }
+    const text = await response.text();
+    /** @type {unknown} */
+    let body;
+    try { body = text ? JSON.parse(text) : null; } catch { body = text; }
+    if (response.status === 200 && useCache) {
+      await writeCache({ key: url, value: body, cwd });
+    }
+    return { status: response.status, body };
+  }
+}
+
+function backoff(attempt) {
+  return Math.min(1000 * 2 ** attempt, 8000);
+}
+function sleep(ms) {
+  return new Promise(res => setTimeout(res, ms));
+}
+
+/**
+ * Resolve a ref (tag, branch, or commit-ish) to an immutable commit SHA.
+ *
+ * @param {object} opts
+ * @param {string} opts.owner
+ * @param {string} opts.repo
+ * @param {string} opts.ref
+ * @param {string} [opts.token]
+ * @param {string} [opts.cwd]
+ * @returns {Promise<{sha: string, type: 'tag'|'branch'|'commit'}>}
+ */
+export async function resolveRefToSha({ owner, repo, ref, token, cwd }) {
+  // Already a full SHA?
+  if (/^[0-9a-f]{40}$/i.test(ref)) {
+    return { sha: ref.toLowerCase(), type: 'commit' };
+  }
+  // Try as tag.
+  const tagUrl = `${API}/repos/${owner}/${repo}/git/refs/tags/${encodeURIComponent(ref)}`;
+  const tagRes = await ghFetch({ url: tagUrl, token, cwd });
+  if (tagRes.status === 200 && tagRes.body && typeof tagRes.body === 'object') {
+    const obj = tagRes.body.object;
+    if (obj && obj.sha) {
+      if (obj.type === 'tag') {
+        // Annotated tag - dereference to commit.
+        const tagObjUrl = `${API}/repos/${owner}/${repo}/git/tags/${obj.sha}`;
+        const tagObj = await ghFetch({ url: tagObjUrl, token, cwd });
+        if (tagObj.status === 200 && tagObj.body && tagObj.body.object) {
+          return { sha: tagObj.body.object.sha, type: 'tag' };
+        }
+      }
+      return { sha: obj.sha, type: 'tag' };
+    }
+  }
+  // Try as branch.
+  const branchUrl = `${API}/repos/${owner}/${repo}/git/refs/heads/${encodeURIComponent(ref)}`;
+  const branchRes = await ghFetch({ url: branchUrl, token, cwd });
+  if (branchRes.status === 200 && branchRes.body?.object?.sha) {
+    return { sha: branchRes.body.object.sha, type: 'branch' };
+  }
+  // Try as commit.
+  const commitUrl = `${API}/repos/${owner}/${repo}/commits/${encodeURIComponent(ref)}`;
+  const commitRes = await ghFetch({ url: commitUrl, token, cwd });
+  if (commitRes.status === 200 && commitRes.body?.sha) {
+    return { sha: commitRes.body.sha, type: 'commit' };
+  }
+  throw new Error(`could not resolve ${owner}/${repo}@${ref}`);
+}
+
+/**
+ * List all tags for a repo (paginated, up to 200).
+ *
+ * @param {object} opts
+ * @param {string} opts.owner
+ * @param {string} opts.repo
+ * @param {string} [opts.token]
+ * @param {string} [opts.cwd]
+ * @returns {Promise<Array<{name: string, sha: string}>>}
+ */
+export async function listTags({ owner, repo, token, cwd }) {
+  /** @type {Array<{name: string, sha: string}>} */
+  const out = [];
+  for (let page = 1; page <= 2; page += 1) {
+    const url = `${API}/repos/${owner}/${repo}/tags?per_page=100&page=${page}`;
+    const res = await ghFetch({ url, token, cwd });
+    if (res.status !== 200 || !Array.isArray(res.body)) break;
+    for (const t of res.body) {
+      if (t && t.name && t.commit?.sha) out.push({ name: t.name, sha: t.commit.sha });
+    }
+    if (res.body.length < 100) break;
+  }
+  return out;
+}
+
+/**
+ * Fetch the committer date of a commit (ms epoch).
+ *
+ * @param {object} opts
+ * @param {string} opts.owner
+ * @param {string} opts.repo
+ * @param {string} opts.sha
+ * @param {string} [opts.token]
+ * @param {string} [opts.cwd]
+ * @returns {Promise<number>}
+ */
+export async function getCommitDate({ owner, repo, sha, token, cwd }) {
+  const url = `${API}/repos/${owner}/${repo}/commits/${encodeURIComponent(sha)}`;
+  const res = await ghFetch({ url, token, cwd });
+  if (res.status !== 200 || !res.body) {
+    throw new Error(`could not fetch commit date for ${owner}/${repo}@${sha}`);
+  }
+  const dateStr = res.body.commit?.committer?.date ?? res.body.commit?.author?.date;
+  if (!dateStr) throw new Error('commit response missing date');
+  const ms = Date.parse(dateStr);
+  if (!Number.isFinite(ms)) throw new Error(`invalid commit date: ${dateStr}`);
+  return ms;
+}
+
+/**
+ * Pick the highest semver tag matching the given policy.
+ *
+ * @param {object} opts
+ * @param {Array<{name: string}>} opts.tags
+ * @param {string|null} opts.currentRef    - current ref ("v3", "v3.1.0", branch)
+ * @param {'major'|'minor'|'patch'} [opts.mode]
+ * @returns {{name: string}|null}
+ */
+export function pickLatestTag({ tags, currentRef, mode = 'major' }) {
+  const semverTags = tags
+    .map(t => ({ tag: t, parsed: semver.coerce(t.name) }))
+    .filter(x => x.parsed)
+    .map(x => ({ tag: x.tag, version: x.parsed.version }))
+    .sort((a, b) => semver.rcompare(a.version, b.version));
+  if (semverTags.length === 0) return null;
+
+  const current = currentRef ? semver.coerce(currentRef) : null;
+  if (!current || mode === 'major') return semverTags[0].tag;
+  for (const candidate of semverTags) {
+    if (mode === 'minor' && semver.major(candidate.version) === current.major) {
+      return candidate.tag;
+    }
+    if (
+      mode === 'patch' &&
+      semver.major(candidate.version) === current.major &&
+      semver.minor(candidate.version) === current.minor
+    ) {
+      return candidate.tag;
+    }
+  }
+  return null;
+}

package/src/lib/writer.js

@@ -0,0 +1,56 @@
+/**
+ * Safe file writer with dry-run guard.
+ *
+ * Every mutation flows through {@link writeFileGuarded}. When `dryRun` is true
+ * (the default), no bytes are written - the change is recorded and reported.
+ */
+
+import { writeFile } from 'node:fs/promises';
+import { resolve, relative } from 'node:path';
+
+/**
+ * @typedef {object} WriteResult
+ * @property {string} path
+ * @property {boolean} written
+ * @property {boolean} dryRun
+ * @property {number} bytes
+ */
+
+/**
+ * @param {object} args
+ * @param {string} args.path
+ * @param {string} args.content
+ * @param {boolean} [args.dryRun]
+ * @param {string} [args.cwd]
+ * @returns {Promise<WriteResult>}
+ */
+export async function writeFileGuarded({ path, content, dryRun = true, cwd = process.cwd() }) {
+  const abs = resolve(cwd, path);
+  const rel = relative(cwd, abs);
+  if (rel.startsWith('..') || rel.includes('\0')) {
+    throw new Error(`refusing to write outside working directory: ${path}`);
+  }
+  const bytes = Buffer.byteLength(content, 'utf8');
+  if (dryRun) {
+    return { path: abs, written: false, dryRun: true, bytes };
+  }
+  await writeFile(abs, content, 'utf8');
+  return { path: abs, written: true, dryRun: false, bytes };
+}
+
+/**
+ * Throws on path traversal attempts.
+ *
+ * @param {string} path
+ * @param {string} [cwd]
+ * @returns {string} absolute path
+ */
+export function assertSafePath(path, cwd = process.cwd()) {
+  if (typeof path !== 'string' || path.includes('\0')) {
+    throw new Error('invalid path');
+  }
+  if (path.includes('..')) {
+    throw new Error(`path traversal rejected: ${path}`);
+  }
+  return resolve(cwd, path);
+}