@cat-factory/executor-harness 1.32.0 → 1.34.0

package/dist/agent.js

@@ -4,6 +4,7 @@ import { mkdir, mkdtemp, opendir, rm } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { standUpFrontend, tearDownFrontend } from './frontend-infra.js';
+import { configurePackageRegistries } from './package-registries.js';
 import { captureRedactedOutput, redactSecrets } from './redact.js';
 import { cloneRepo, commitAll, conflictDiff, hasAgentChanges, headCommit, mergeBranch, openPullRequest, prepareExistingCheckout, pushBranch, reinitAndPush, unmergedPaths, } from './git.js';
 import { noChangesReason, runCodingAgent } from './coding-agent.js';
@@ -196,6 +197,11 @@ async function cloneServiceCheckout(dir, job, signal) {
 }
 /** Run one generic agent job end to end, dispatching on `mode`. */
 export async function handleAgent(job, opts = {}) {
+    // Private-registry auth first, before any mode runs: every mode with a checkout may
+    // install dependencies (the agent's own shell and the frontend-infra stand-up both
+    // inherit `HOME`, so they all read the written ~/.npmrc). A job with no entries
+    // clears any stale ~/.npmrc from a prior job on a reused (warm-pool) container.
+    await configurePackageRegistries(job.packageRegistries);
     if (job.mode === 'preview')
         return runPreviewMode(job, opts);
     return job.mode === 'coding' ? runCodingMode(job, opts) : runExploreMode(job, opts);

package/dist/job.js

@@ -165,6 +165,63 @@ function assertAllowedHost(rawUrl, path, env = process.env) {
         throw new Error(`Invalid job: '${path}' host '${host}' is not an allowed GitHub host`);
     }
 }
+/** npm registry hosts the harness is willing to send a registry token to. */
+export function allowedNpmRegistryHosts(env = process.env) {
+    const hosts = new Set(['registry.npmjs.org', 'npm.pkg.github.com']);
+    // Optional extra allowlist (comma-separated) for tests / bespoke deployments.
+    for (const h of (env.NPM_ALLOWED_REGISTRY_HOSTS ?? '').split(',')) {
+        const t = h.trim().toLowerCase();
+        if (t)
+            hosts.add(t);
+    }
+    return hosts;
+}
+/** An npm scope (`@org`) — same shape the backend validates at the write boundary. */
+const NPM_SCOPE_PATTERN = /^@[a-z0-9~-][a-z0-9._~-]*$/i;
+// A registry token is a single opaque string. Reject any whitespace / control
+// character: a newline in the token would inject arbitrary lines into the rendered
+// `~/.npmrc` (a second, forged registry/_authToken line). Mirrors the backend's
+// write-boundary constraint so a drifted body can't slip a multiline token past.
+const NPM_TOKEN_PATTERN = /^[\x21-\x7e]+$/;
+/** Validate the optional `packageRegistries` list (see {@link PackageRegistrySpec}). */
+export function parsePackageRegistries(value, env = process.env) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error("Invalid job: 'packageRegistries' must be an array");
+    const allowed = allowedNpmRegistryHosts(env);
+    const entries = [];
+    for (const [i, raw] of value.entries()) {
+        if (typeof raw !== 'object' || raw === null) {
+            throw new Error(`Invalid job: 'packageRegistries[${i}]' must be an object`);
+        }
+        const entry = raw;
+        // Unknown ecosystems are additive: a newer backend may send pip/maven entries an
+        // older image doesn't understand yet — skip them rather than failing the job.
+        if (entry.ecosystem !== 'npm')
+            continue;
+        const host = str(entry.host, `packageRegistries[${i}].host`).trim().toLowerCase();
+        if (!allowed.has(host)) {
+            throw new Error(`Invalid job: 'packageRegistries[${i}].host' '${host}' is not an allowed npm registry host`);
+        }
+        if (!Array.isArray(entry.scopes) || entry.scopes.length === 0) {
+            throw new Error(`Invalid job: 'packageRegistries[${i}].scopes' must be a non-empty array`);
+        }
+        const scopes = entry.scopes.map((scope, j) => {
+            const s = str(scope, `packageRegistries[${i}].scopes[${j}]`).trim();
+            if (!NPM_SCOPE_PATTERN.test(s)) {
+                throw new Error(`Invalid job: 'packageRegistries[${i}].scopes[${j}]' must look like @org`);
+            }
+            return s;
+        });
+        const token = str(entry.token, `packageRegistries[${i}].token`);
+        if (!NPM_TOKEN_PATTERN.test(token)) {
+            throw new Error(`Invalid job: 'packageRegistries[${i}].token' must not contain spaces or control characters`);
+        }
+        entries.push({ ecosystem: 'npm', host, scopes, token });
+    }
+    return entries;
+}
 /** Parse the coding-mode bootstrap spec, or undefined when absent. Validates the target. */
 function parseAgentBootstrapSpec(value) {
     if (typeof value !== 'object' || value === null)
@@ -372,6 +429,7 @@ export function parseAgentJob(input) {
     const infra = parseAgentInfraSpec(o.infra);
     const bootstrap = parseAgentBootstrapSpec(o.bootstrap);
     const contextFiles = parseContextFiles(o.contextFiles);
+    const packageRegistries = parsePackageRegistries(o.packageRegistries);
     const guardLimits = parseGuardLimits(o.guardLimits);
     const job = {
         jobId: str(o.jobId, 'jobId'),
@@ -391,6 +449,7 @@ export function parseAgentJob(input) {
         ...(bootstrap ? { bootstrap } : {}),
         ...(output ? { output } : {}),
         ...(contextFiles.length ? { contextFiles } : {}),
+        ...(packageRegistries.length ? { packageRegistries } : {}),
         ...(infra ? { infra } : {}),
         ...(typeof o.newBranch === 'string' && o.newBranch ? { newBranch: o.newBranch } : {}),
         ...(typeof o.pushBranch === 'string' && o.pushBranch ? { pushBranch: o.pushBranch } : {}),

package/dist/package-registries.js

@@ -0,0 +1,51 @@
+import { chmod, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { registerKnownSecrets } from './redact.js';
+// Private package-registry auth for the checkout's installs (npm private orgs,
+// GitHub Packages). The job's allowlisted entries are rendered into the USER
+// `~/.npmrc` — read by npm, pnpm and yarn v1 alike, and inherited by every child
+// process (the agent's own shell installs and the frontend-infra stand-up's) — so
+// the token never rides argv or the checkout. Written per job; a job with NO
+// entries removes any stale file, because warm-pool containers are reused across
+// jobs and must not leak a prior workspace's token.
+/** Where the per-job npm auth lands (the user npmrc, outside any checkout). */
+export function npmrcPath() {
+    return join(homedir(), '.npmrc');
+}
+/**
+ * Render the job's registry entries as npmrc lines: each scope routed to its
+ * registry, plus one `_authToken` credential line per distinct host.
+ */
+export function renderNpmrc(entries) {
+    const lines = [];
+    const hosts = new Map();
+    for (const entry of entries) {
+        for (const scope of entry.scopes) {
+            lines.push(`${scope}:registry=https://${entry.host}/`);
+        }
+        // Last entry wins per host — entries for the same host carry the same vendor
+        // token in practice (the backend stores one token per entry).
+        hosts.set(entry.host, entry.token);
+    }
+    for (const [host, token] of hosts) {
+        lines.push(`//${host}/:_authToken=${token}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * Write (or clear) the per-job `~/.npmrc` before the agent runs. Tokens are
+ * registered for output redaction so a token echoed in an npm error never reaches
+ * logs or stored output.
+ */
+export async function configurePackageRegistries(entries) {
+    const path = npmrcPath();
+    if (!entries || entries.length === 0) {
+        await rm(path, { force: true });
+        return;
+    }
+    registerKnownSecrets(entries.map((entry) => entry.token));
+    await writeFile(path, renderNpmrc(entries), { mode: 0o600 });
+    // writeFile's mode only applies on create — tighten an existing file too.
+    await chmod(path, 0o600);
+}

package/dist/redact.js

@@ -28,12 +28,25 @@ const MIN_HARVEST_LEN = 12;
 // `DB_ACCESS_KEY`/`api_key` are covered; `auth` is deliberately excluded so it can't
 // clobber a git `Author:` line. The value is the first whitespace-delimited run.
 const CREDENTIAL_ASSIGNMENT = /\b([A-Za-z0-9_]*(?:password|passwd|pwd|secret|token|key|credential)[A-Za-z0-9_]*\s*[:=]\s*)\S+/gi;
+// Known-secret values registered per JOB (e.g. the job's private-registry tokens),
+// scrubbed on EVERY redaction — including the pattern-only `redactSecrets` call sites
+// that carry no per-call secret list. Accumulating across jobs on a reused container
+// is safe: redaction only ever widens.
+const REGISTERED_SECRETS = new Set();
+/** Register known secret values to scrub on every subsequent redaction. */
+export function registerKnownSecrets(values) {
+    for (const value of values) {
+        if (value && value.length >= MIN_REDACT_LEN)
+            REGISTERED_SECRETS.add(value);
+    }
+}
 /**
  * Strip credentials out of any string before it is logged or stored. Applies the
  * pattern rules (URL userinfo `https://user:pass@host`, `x-access-token:<token>`, bare
  * `ghs_`/`ghp_`/`gho_`/`github_pat_` shapes, and credential-named `KEY=value` / `KEY:
- * value` assignments) and then scrubs every supplied known-secret value. Idempotent —
- * safe to call on already-redacted text.
+ * value` assignments) and then scrubs every supplied known-secret value plus the
+ * module-registered ones ({@link registerKnownSecrets}). Idempotent — safe to call on
+ * already-redacted text.
  */
 export function redact(input, knownSecrets = []) {
     let out = input
@@ -41,14 +54,14 @@ export function redact(input, knownSecrets = []) {
         .replace(/x-access-token:[^@\s]+/gi, 'x-access-token:***')
         .replace(/\b(gh[pso]_|github_pat_)[A-Za-z0-9_]+/g, '$1***')
         .replace(CREDENTIAL_ASSIGNMENT, '$1***');
-    for (const secret of knownSecrets) {
+    for (const secret of [...knownSecrets, ...REGISTERED_SECRETS]) {
         // Guard against scrubbing trivially-short values that would mangle output.
         if (secret.length >= MIN_REDACT_LEN)
             out = out.split(secret).join('***');
     }
     return out;
 }
-/** Pattern-only redaction (no known values). Kept for callers without a secret list. */
+/** Pattern + registered-value redaction. Kept for callers without a per-call secret list. */
 export function redactSecrets(input) {
     return redact(input);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.32.0",
+  "version": "1.34.0",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -26,8 +26,8 @@
     "hono": "^4.12.27",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9",
-    "@cat-factory/server": "0.68.0",
-    "@cat-factory/spend": "0.10.74"
+    "@cat-factory/server": "0.69.0",
+    "@cat-factory/spend": "0.10.77"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent.ts

@@ -11,6 +11,7 @@ import type {
   ServiceInfraSpec,
 } from './job.js'
 import { standUpFrontend, tearDownFrontend } from './frontend-infra.js'
+import { configurePackageRegistries } from './package-registries.js'
 import { captureRedactedOutput, redactSecrets } from './redact.js'
 import {
   cloneRepo,
@@ -263,6 +264,11 @@ async function cloneServiceCheckout(
 
 /** Run one generic agent job end to end, dispatching on `mode`. */
 export async function handleAgent(job: AgentJob, opts: RunOptions = {}): Promise<AgentResult> {
+  // Private-registry auth first, before any mode runs: every mode with a checkout may
+  // install dependencies (the agent's own shell and the frontend-infra stand-up both
+  // inherit `HOME`, so they all read the written ~/.npmrc). A job with no entries
+  // clears any stale ~/.npmrc from a prior job on a reused (warm-pool) container.
+  await configurePackageRegistries(job.packageRegistries)
   if (job.mode === 'preview') return runPreviewMode(job, opts)
   return job.mode === 'coding' ? runCodingMode(job, opts) : runExploreMode(job, opts)
 }

package/src/job.ts

@@ -232,6 +232,89 @@ function assertAllowedHost(
   }
 }
 
+// ---- Private package registries ------------------------------------------
+// Workspace-configured private-registry auth (npm private orgs, GitHub Packages)
+// so the checkout's installs resolve private dependencies. The backend derives the
+// host from a fixed vendor set, so the harness hard-allowlists where a registry
+// token may be sent — a body-supplied host outside the allowlist is treated as
+// forgery (token exfiltration) and rejects the job. Ecosystem-discriminated:
+// entries of an unknown ecosystem are DROPPED (not an error) so later ecosystems
+// (pip/maven/cargo) stay additive for an older harness image.
+
+/** One private-registry entry: rendered into `~/.npmrc` before the agent runs. */
+export interface PackageRegistrySpec {
+  ecosystem: 'npm'
+  /** Registry host, e.g. `registry.npmjs.org` — allowlisted, never a full URL. */
+  host: string
+  /** npm scopes (`@org`) routed to this registry. */
+  scopes: string[]
+  token: string
+}
+
+/** npm registry hosts the harness is willing to send a registry token to. */
+export function allowedNpmRegistryHosts(env: NodeJS.ProcessEnv = process.env): Set<string> {
+  const hosts = new Set(['registry.npmjs.org', 'npm.pkg.github.com'])
+  // Optional extra allowlist (comma-separated) for tests / bespoke deployments.
+  for (const h of (env.NPM_ALLOWED_REGISTRY_HOSTS ?? '').split(',')) {
+    const t = h.trim().toLowerCase()
+    if (t) hosts.add(t)
+  }
+  return hosts
+}
+
+/** An npm scope (`@org`) — same shape the backend validates at the write boundary. */
+const NPM_SCOPE_PATTERN = /^@[a-z0-9~-][a-z0-9._~-]*$/i
+
+// A registry token is a single opaque string. Reject any whitespace / control
+// character: a newline in the token would inject arbitrary lines into the rendered
+// `~/.npmrc` (a second, forged registry/_authToken line). Mirrors the backend's
+// write-boundary constraint so a drifted body can't slip a multiline token past.
+const NPM_TOKEN_PATTERN = /^[\x21-\x7e]+$/
+
+/** Validate the optional `packageRegistries` list (see {@link PackageRegistrySpec}). */
+export function parsePackageRegistries(
+  value: unknown,
+  env: NodeJS.ProcessEnv = process.env,
+): PackageRegistrySpec[] {
+  if (value === undefined || value === null) return []
+  if (!Array.isArray(value)) throw new Error("Invalid job: 'packageRegistries' must be an array")
+  const allowed = allowedNpmRegistryHosts(env)
+  const entries: PackageRegistrySpec[] = []
+  for (const [i, raw] of value.entries()) {
+    if (typeof raw !== 'object' || raw === null) {
+      throw new Error(`Invalid job: 'packageRegistries[${i}]' must be an object`)
+    }
+    const entry = raw as Record<string, unknown>
+    // Unknown ecosystems are additive: a newer backend may send pip/maven entries an
+    // older image doesn't understand yet — skip them rather than failing the job.
+    if (entry.ecosystem !== 'npm') continue
+    const host = str(entry.host, `packageRegistries[${i}].host`).trim().toLowerCase()
+    if (!allowed.has(host)) {
+      throw new Error(
+        `Invalid job: 'packageRegistries[${i}].host' '${host}' is not an allowed npm registry host`,
+      )
+    }
+    if (!Array.isArray(entry.scopes) || entry.scopes.length === 0) {
+      throw new Error(`Invalid job: 'packageRegistries[${i}].scopes' must be a non-empty array`)
+    }
+    const scopes = entry.scopes.map((scope, j) => {
+      const s = str(scope, `packageRegistries[${i}].scopes[${j}]`).trim()
+      if (!NPM_SCOPE_PATTERN.test(s)) {
+        throw new Error(`Invalid job: 'packageRegistries[${i}].scopes[${j}]' must look like @org`)
+      }
+      return s
+    })
+    const token = str(entry.token, `packageRegistries[${i}].token`)
+    if (!NPM_TOKEN_PATTERN.test(token)) {
+      throw new Error(
+        `Invalid job: 'packageRegistries[${i}].token' must not contain spaces or control characters`,
+      )
+    }
+    entries.push({ ecosystem: 'npm', host, scopes, token })
+  }
+  return entries
+}
+
 // ---- Shared repo-bootstrap target ---------------------------------------
 
 /** The new repository a repo-bootstrap run force-pushes its fresh history to. */
@@ -412,6 +495,14 @@ export interface AgentJob extends HarnessAuthFields {
    * The agent reads them on demand; they are kept out of any commit. Absent ⇒ none.
    */
   contextFiles?: ContextFileSpec[]
+  /**
+   * Private package-registry auth (npm private orgs, GitHub Packages), rendered into
+   * `~/.npmrc` before the run so the checkout's installs — the agent's own and the
+   * frontend-infra stand-up's — resolve private dependencies. Hosts are hard-allowlisted
+   * (see {@link allowedNpmRegistryHosts}). Absent ⇒ any stale `~/.npmrc` from a prior
+   * job on a reused container is removed.
+   */
+  packageRegistries?: PackageRegistrySpec[]
   /**
    * Explore mode: stand the service's dependencies up before the agent runs (the
    * tester). Brings the docker-compose infra up on localhost for the duration of the
@@ -746,6 +837,7 @@ export function parseAgentJob(input: unknown): AgentJob {
   const infra = parseAgentInfraSpec(o.infra)
   const bootstrap = parseAgentBootstrapSpec(o.bootstrap)
   const contextFiles = parseContextFiles(o.contextFiles)
+  const packageRegistries = parsePackageRegistries(o.packageRegistries)
   const guardLimits = parseGuardLimits(o.guardLimits)
   const job: AgentJob = {
     jobId: str(o.jobId, 'jobId'),
@@ -765,6 +857,7 @@ export function parseAgentJob(input: unknown): AgentJob {
     ...(bootstrap ? { bootstrap } : {}),
     ...(output ? { output } : {}),
     ...(contextFiles.length ? { contextFiles } : {}),
+    ...(packageRegistries.length ? { packageRegistries } : {}),
     ...(infra ? { infra } : {}),
     ...(typeof o.newBranch === 'string' && o.newBranch ? { newBranch: o.newBranch } : {}),
     ...(typeof o.pushBranch === 'string' && o.pushBranch ? { pushBranch: o.pushBranch } : {}),

package/src/package-registries.ts

@@ -0,0 +1,58 @@
+import { chmod, rm, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import type { PackageRegistrySpec } from './job.js'
+import { registerKnownSecrets } from './redact.js'
+
+// Private package-registry auth for the checkout's installs (npm private orgs,
+// GitHub Packages). The job's allowlisted entries are rendered into the USER
+// `~/.npmrc` — read by npm, pnpm and yarn v1 alike, and inherited by every child
+// process (the agent's own shell installs and the frontend-infra stand-up's) — so
+// the token never rides argv or the checkout. Written per job; a job with NO
+// entries removes any stale file, because warm-pool containers are reused across
+// jobs and must not leak a prior workspace's token.
+
+/** Where the per-job npm auth lands (the user npmrc, outside any checkout). */
+export function npmrcPath(): string {
+  return join(homedir(), '.npmrc')
+}
+
+/**
+ * Render the job's registry entries as npmrc lines: each scope routed to its
+ * registry, plus one `_authToken` credential line per distinct host.
+ */
+export function renderNpmrc(entries: readonly PackageRegistrySpec[]): string {
+  const lines: string[] = []
+  const hosts = new Map<string, string>()
+  for (const entry of entries) {
+    for (const scope of entry.scopes) {
+      lines.push(`${scope}:registry=https://${entry.host}/`)
+    }
+    // Last entry wins per host — entries for the same host carry the same vendor
+    // token in practice (the backend stores one token per entry).
+    hosts.set(entry.host, entry.token)
+  }
+  for (const [host, token] of hosts) {
+    lines.push(`//${host}/:_authToken=${token}`)
+  }
+  return `${lines.join('\n')}\n`
+}
+
+/**
+ * Write (or clear) the per-job `~/.npmrc` before the agent runs. Tokens are
+ * registered for output redaction so a token echoed in an npm error never reaches
+ * logs or stored output.
+ */
+export async function configurePackageRegistries(
+  entries: readonly PackageRegistrySpec[] | undefined,
+): Promise<void> {
+  const path = npmrcPath()
+  if (!entries || entries.length === 0) {
+    await rm(path, { force: true })
+    return
+  }
+  registerKnownSecrets(entries.map((entry) => entry.token))
+  await writeFile(path, renderNpmrc(entries), { mode: 0o600 })
+  // writeFile's mode only applies on create — tighten an existing file too.
+  await chmod(path, 0o600)
+}

package/src/redact.ts

@@ -33,12 +33,26 @@ const MIN_HARVEST_LEN = 12
 const CREDENTIAL_ASSIGNMENT =
   /\b([A-Za-z0-9_]*(?:password|passwd|pwd|secret|token|key|credential)[A-Za-z0-9_]*\s*[:=]\s*)\S+/gi
 
+// Known-secret values registered per JOB (e.g. the job's private-registry tokens),
+// scrubbed on EVERY redaction — including the pattern-only `redactSecrets` call sites
+// that carry no per-call secret list. Accumulating across jobs on a reused container
+// is safe: redaction only ever widens.
+const REGISTERED_SECRETS = new Set<string>()
+
+/** Register known secret values to scrub on every subsequent redaction. */
+export function registerKnownSecrets(values: readonly string[]): void {
+  for (const value of values) {
+    if (value && value.length >= MIN_REDACT_LEN) REGISTERED_SECRETS.add(value)
+  }
+}
+
 /**
  * Strip credentials out of any string before it is logged or stored. Applies the
  * pattern rules (URL userinfo `https://user:pass@host`, `x-access-token:<token>`, bare
  * `ghs_`/`ghp_`/`gho_`/`github_pat_` shapes, and credential-named `KEY=value` / `KEY:
- * value` assignments) and then scrubs every supplied known-secret value. Idempotent —
- * safe to call on already-redacted text.
+ * value` assignments) and then scrubs every supplied known-secret value plus the
+ * module-registered ones ({@link registerKnownSecrets}). Idempotent — safe to call on
+ * already-redacted text.
  */
 export function redact(input: string, knownSecrets: readonly string[] = []): string {
   let out = input
@@ -46,14 +60,14 @@ export function redact(input: string, knownSecrets: readonly string[] = []): str
     .replace(/x-access-token:[^@\s]+/gi, 'x-access-token:***')
     .replace(/\b(gh[pso]_|github_pat_)[A-Za-z0-9_]+/g, '$1***')
     .replace(CREDENTIAL_ASSIGNMENT, '$1***')
-  for (const secret of knownSecrets) {
+  for (const secret of [...knownSecrets, ...REGISTERED_SECRETS]) {
     // Guard against scrubbing trivially-short values that would mangle output.
     if (secret.length >= MIN_REDACT_LEN) out = out.split(secret).join('***')
   }
   return out
 }
 
-/** Pattern-only redaction (no known values). Kept for callers without a secret list. */
+/** Pattern + registered-value redaction. Kept for callers without a per-call secret list. */
 export function redactSecrets(input: string): string {
   return redact(input)
 }