@natjswenson/shipflow 0.2.2 → 0.2.4

package/SKILL.md

@@ -115,6 +115,7 @@ This is a **separate, later invocation** from the one that ran the promotion's `
 - All `gh`/`git` invocations in the CLI are argv-style (`spawnSync` with an args array, no shell) — never construct a shell command string from user input when extending this skill.
 - `.github/shipflow.json` is committed policy, not secrets — never write credential *values* into it, only the *name* of a secret (`release.releaseCredential`).
 - Never write shipflow's config anywhere other than `.github/shipflow.json` in the target repo.
+- **`renderTemplate` validates every substituted value before writing YAML, and this must never be weakened.** `config.branches.dev`/`main` and `release.releaseCredential` are editable by anyone with repo *write* access (not just the admin who ran setup), yet they land in single-quoted YAML string comparisons and a `${{ secrets.X }}` expression with pure string substitution. An unvalidated branch name containing a quote (e.g. `dev' || 'x'=='x`) makes the auto-merge job's `if:` condition unconditionally true — auto-merge would enable on *any* PR to main, not just genuine dev-branch promotions; a value containing a newline can inject arbitrary new YAML steps into the committed, then-executed workflow. If you add a new substitution token, it needs a validator in `TOKEN_VALIDATORS` before it ships — never assume a config field is pre-sanitized.
 
 ## Edge cases
 

package/bin/shipflow.js

@@ -14,6 +14,7 @@ import {
   dispatchReleaseWorkflow,
   renameDefaultBranch,
 } from '../lib/apply.mjs';
+import { readFileCapped } from '../lib/gh.mjs';
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const TEMPLATE_PATH = join(PACKAGE_ROOT, 'templates', 'dev-to-main-automerge.yml.tmpl');
@@ -24,7 +25,10 @@ function readPackageVersion() {
 }
 
 function readConfig(path) {
-  return JSON.parse(readFileSync(path, 'utf8'));
+  // .github/shipflow.json lives in whatever repo --repo points at — a
+  // repo-write-editable file, not admin-only — so cap its size before
+  // parsing (see lib/gh.mjs's readFileCapped for why).
+  return JSON.parse(readFileCapped(path));
 }
 
 function defaultConfigPath(repoPath) {
@@ -85,7 +89,12 @@ function cmdPlan(args) {
     releaseCredentialName: config.release?.releaseCredential ?? null,
   });
   const templateSource = readFileSync(TEMPLATE_PATH, 'utf8');
-  const plan = computePlan(repoState, config, templateSource);
+  let plan;
+  try {
+    plan = computePlan(repoState, config, templateSource);
+  } catch (e) {
+    return fail(`plan: ${e.message}`);
+  }
   printJson({ plan, stateHash: repoState.stateHash });
 }
 
@@ -122,7 +131,12 @@ function cmdApply(args) {
     releaseCredentialName: config.release?.releaseCredential ?? null,
   });
   const templateSource = readFileSync(TEMPLATE_PATH, 'utf8');
-  const plan = computePlan(repoState, config, templateSource);
+  let plan;
+  try {
+    plan = computePlan(repoState, config, templateSource);
+  } catch (e) {
+    return fail(`apply: ${e.message}`);
+  }
 
   // The CLI-level TOCTOU gate: compare the freshly-detected state against
   // what the user confirmed at plan time (--expect-state-hash, captured

package/lib/detect.mjs

@@ -1,6 +1,6 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { spawnArgs, ghApiJson, git, sha256 } from './gh.mjs';
+import { spawnArgs, ghApiJson, git, sha256, readFileCapped } from './gh.mjs';
 
 const TEMPLATE_RELATIVE_PATH = '.github/workflows/dev-to-main-automerge.yml';
 const CONFIG_RELATIVE_PATH = '.github/shipflow.json';
@@ -14,11 +14,20 @@ const SETTINGS_AS_CODE_NAME_RE = /repo-settings\.(sh|js|mjs|py)$/i;
 const SETTINGS_AS_CODE_CONTENT_RE =
   /github_branch_protection|github_repository_ruleset|branches\/[\w-]+\/protection/;
 
+// A segment made of only dots ("." / ".." / "...") matches [\w.-]+ but is
+// never a real GitHub owner or repo name — reject it rather than build an
+// ownerRepo string that could normalize away the intended repos/<owner>/<repo>
+// prefix once interpolated into gh api paths downstream.
+const ALL_DOTS_RE = /^\.+$/;
+
 export function resolveOwnerRepo(repoPath) {
   const r = git(['remote', 'get-url', 'origin'], { cwd: repoPath });
   if (r.status !== 0) return null;
   const m = r.stdout.match(/github\.com[:/]([\w.-]+)\/([\w.-]+?)(\.git)?$/);
-  return m ? `${m[1]}/${m[2]}` : null;
+  if (!m) return null;
+  const [, owner, repo] = m;
+  if (ALL_DOTS_RE.test(owner) || ALL_DOTS_RE.test(repo)) return null;
+  return `${owner}/${repo}`;
 }
 
 export function listTrackedFiles(repoPath) {
@@ -42,7 +51,7 @@ export function findSettingsAsCodeArtifact(repoPath, trackedFiles) {
     if (!existsSync(full)) continue;
     let content;
     try {
-      content = readFileSync(full, 'utf8');
+      content = readFileCapped(full);
     } catch {
       continue;
     }
@@ -66,7 +75,7 @@ export function listWorkflowJobNames(repoPath, trackedFiles) {
     if (!existsSync(full)) continue;
     let content;
     try {
-      content = readFileSync(full, 'utf8');
+      content = readFileCapped(full);
     } catch {
       continue;
     }
@@ -87,7 +96,7 @@ export function listWorkflowJobNames(repoPath, trackedFiles) {
 export function readTemplateFileHash(repoPath) {
   const full = join(repoPath, TEMPLATE_RELATIVE_PATH);
   if (!existsSync(full)) return { exists: false, sha256: null };
-  const content = readFileSync(full, 'utf8');
+  const content = readFileCapped(full);
   return { exists: true, sha256: sha256(content) };
 }
 
@@ -95,14 +104,14 @@ export function readExistingConfig(repoPath) {
   const full = join(repoPath, CONFIG_RELATIVE_PATH);
   if (!existsSync(full)) return null;
   try {
-    return JSON.parse(readFileSync(full, 'utf8'));
+    return JSON.parse(readFileCapped(full));
   } catch {
     return null;
   }
 }
 
 export function fetchBranchProtection(ownerRepo, branch) {
-  const r = ghApiJson(`repos/${ownerRepo}/branches/${branch}/protection`);
+  const r = ghApiJson(`repos/${ownerRepo}/branches/${encodeURIComponent(branch)}/protection`);
   if (!r.ok) return null;
   const checks = r.data?.required_status_checks?.contexts ?? [];
   return { requiredChecks: checks, raw: r.data };
@@ -133,7 +142,7 @@ export function fetchRulesetRequiredChecks(ownerRepo, rulesetId) {
 }
 
 export function checkSecretPresent(ownerRepo, secretName) {
-  const r = ghApiJson(`repos/${ownerRepo}/actions/secrets/${secretName}`);
+  const r = ghApiJson(`repos/${ownerRepo}/actions/secrets/${encodeURIComponent(secretName)}`);
   return r.ok;
 }
 

package/lib/gh.mjs

@@ -1,6 +1,23 @@
 import { spawnSync } from 'node:child_process';
+import { statSync, readFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 
+// Every file shipflow reads under a target repo (.github/shipflow.json,
+// candidate settings-as-code artifacts, workflow YAML, the rendered
+// template on disk) is repo-write-controlled, not admin-only — a
+// maliciously huge or pathologically nested file could exhaust memory on
+// an unbounded readFileSync/JSON.parse. 1 MB is generous for any
+// legitimate config/workflow/IaC file shipflow actually needs to read.
+const MAX_READ_BYTES = 1_000_000;
+
+export function readFileCapped(path, encoding = 'utf8') {
+  const size = statSync(path).size;
+  if (size > MAX_READ_BYTES) {
+    throw new Error(`refusing to read ${path}: ${size} bytes exceeds the ${MAX_READ_BYTES}-byte safety cap`);
+  }
+  return readFileSync(path, encoding);
+}
+
 // argv-style invocation; no shell, so user-supplied args cannot inject.
 // Returns { status, stdout, stderr } so callers can distinguish failure modes
 // (e.g. a 404 from gh vs. a network error) instead of collapsing to a boolean.

package/lib/render.mjs

@@ -14,6 +14,34 @@
 
 const TOKEN_RE = /\{\{(\w+)\}\}/g;
 
+// DEV_BRANCH/MAIN_BRANCH land inside single-quoted YAML string comparisons
+// (`... == '{{DEV_BRANCH}}'`) and RELEASE_CREDENTIAL_SECRET lands inside a
+// `${{ secrets.X }}` GitHub Actions expression — this function does pure
+// string substitution with NO awareness of YAML or GHA-expression grammar,
+// so any of these three params can break out of their quoting context if
+// not validated first. Concretely: devBranch = "dev' || 'x'=='x" renders
+// the auto-merge job's `if:` condition to `... == 'dev' || 'x'=='x'`,
+// which is unconditionally true — enabling auto-merge on ANY pull request
+// to main, not just genuine dev-branch promotions. A value containing a
+// newline in any of the three can inject entirely new YAML keys/steps into
+// the committed, then-executed workflow file. This is not a theoretical
+// input: config.branches.{main,dev} and config.release.releaseCredential
+// come from .github/shipflow.json, a file anyone with repo WRITE access
+// (not just the admin who ran shipflow's setup) can edit — a strictly
+// lower trust level than the admin-scoped `gh` credential the rendered
+// workflow runs with. Found via a Siege security audit (2026-07-15).
+const UNSAFE_YAML_STRING_RE = /['\r\n]/;
+// GitHub Actions secret names: letters, digits, underscore; cannot start
+// with a digit (case-insensitivity aside, this is the full safe charset).
+const SAFE_SECRET_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+const TOKEN_VALIDATORS = Object.freeze({
+  DEV_BRANCH: (v) => !UNSAFE_YAML_STRING_RE.test(v),
+  MAIN_BRANCH: (v) => !UNSAFE_YAML_STRING_RE.test(v),
+  MERGE_FLAG: () => true, // closed enum from mergeMethodToFlag — never attacker-shaped
+  RELEASE_CREDENTIAL_SECRET: (v) => SAFE_SECRET_NAME_RE.test(v),
+});
+
 // params: { devBranch, mainBranch, mergeFlag, releaseCredentialSecret }
 // mergeFlag is one of "--merge" | "--squash" | "--rebase", derived from
 // config.mergeMethod.devToMainMethod by the caller (not this function —
@@ -22,17 +50,28 @@ const TOKEN_RE = /\{\{(\w+)\}\}/g;
 // config shape, only of the template's token names).
 export function renderTemplate(templateSource, params) {
   const missing = [];
+  const unsafe = [];
   const rendered = templateSource.replace(TOKEN_RE, (_, name) => {
     const key = TOKEN_TO_PARAM[name];
     if (!key || !(key in params)) {
       missing.push(name);
       return `{{${name}}}`;
     }
-    return String(params[key]);
+    const value = String(params[key]);
+    const validate = TOKEN_VALIDATORS[name];
+    if (validate && !validate(value)) {
+      unsafe.push(name);
+    }
+    return value;
   });
   if (missing.length > 0) {
     throw new Error(`renderTemplate: missing param(s) for token(s): ${missing.join(', ')}`);
   }
+  if (unsafe.length > 0) {
+    throw new Error(
+      `renderTemplate: unsafe value for token(s): ${unsafe.join(', ')} — branch names must not contain a quote or newline, and the release-credential secret name must match GitHub's secret-naming rules (letters/digits/underscore, not starting with a digit)`
+    );
+  }
   return rendered;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@natjswenson/shipflow",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Scaffold a configurable dev/main branching, auto-merge, branch-cleanup, and release-tagging workflow into any repo",
   "license": "MIT",
   "author": "Nate Swenson",

package/skill-invariants.json

@@ -60,6 +60,11 @@
       "id": "release-credential-never-github-token",
       "pattern": "never default it to `GITHUB_TOKEN`",
       "rationale": "Found by dogfooding on claude-skills itself (2026-07-15): a PR auto-merged under secrets.GITHUB_TOKEN completes attributed to github-actions[bot], and GitHub's loop-prevention rule means that bot-attributed merge's pull_request:closed event never triggers label-release-pending — the entire manual-gate release-ask flow silently never has anything to find unless releaseCredential names a real PAT."
+    },
+    {
+      "id": "render-template-validates-substitutions",
+      "pattern": "never assume a config field is pre-sanitized",
+      "rationale": "Found by a Siege security audit (2026-07-15): renderTemplate did pure string substitution with zero escaping, so a repo-write-level (not admin-level) edit to .github/shipflow.json's branch names or release.releaseCredential could break out of the rendered YAML's quoting and make the auto-merge job's if: condition unconditionally true, or inject arbitrary new workflow steps — a privilege escalation via the credential the rendered workflow runs with."
     }
   ],
   "cli_commands_referenced": ["detect", "plan", "apply", "releases", "release-dispatch", "rename-default-branch"]