@kici-dev/agent 0.6.1 → 0.7.0

package/dist/index.js

@@ -105,6 +105,10 @@ const configSchema = z.object({
 	sandboxHardened: z.string().default("true").transform((s) => s !== "false"),
 	sandboxReadonlyRootfs: z.string().default("false").transform((s) => s === "true"),
 	sandboxUser: z.string().optional(),
+	runnerUser: z.string().optional(),
+	runnerDebugStdio: z.string().default("false").transform((s) => s === "true"),
+	sandboxNetworkIsolation: z.string().default("true").transform((s) => s !== "false"),
+	allowInstallScripts: z.string().default("false").transform((s) => s === "true"),
 	sandboxPidsLimit: z.coerce.number().int().positive().default(512),
 	sandboxMemoryBytes: z.coerce.number().int().positive().default(2147483648),
 	sandboxNanoCpus: z.coerce.number().int().positive().default(2e9),
@@ -159,6 +163,10 @@ const envDef = defineEnv({
 		sandboxHardened: "KICI_SANDBOX_HARDENED",
 		sandboxReadonlyRootfs: "KICI_SANDBOX_READONLY_ROOTFS",
 		sandboxUser: "KICI_SANDBOX_USER",
+		runnerUser: "KICI_RUNNER_USER",
+		runnerDebugStdio: "KICI_RUNNER_DEBUG_STDIO",
+		sandboxNetworkIsolation: "KICI_SANDBOX_NETWORK_ISOLATION",
+		allowInstallScripts: "KICI_ALLOW_INSTALL_SCRIPTS",
 		sandboxPidsLimit: "KICI_SANDBOX_PIDS_LIMIT",
 		sandboxMemoryBytes: "KICI_SANDBOX_MEMORY_BYTES",
 		sandboxNanoCpus: "KICI_SANDBOX_NANO_CPUS",
@@ -212,6 +220,10 @@ const envDef = defineEnv({
 * - KICI_SCALER_CLAIM_CODE (optional single-use claim code the agent exchanges for its own ephemeral credentials before registering; ignored when KICI_AGENT_TOKEN is set)
 * - KICI_SCALER_IDLE_TIMEOUT (ms, default 5000) — how long a scaler-managed agent waits before shutdown after going idle
 * - KICI_SCALER_PENDING_DISPATCH_TIMEOUT (ms, default 60000) — extended idle window when register.ack signals a queued bound job
+* - KICI_RUNNER_USER (optional, uid | uid:gid | name) — run the bare-metal runner child as a dedicated user instead of the agent's own
+* - KICI_ALLOW_INSTALL_SCRIPTS (default: false) — re-enable package lifecycle scripts during the `.kici/` dependency install
+* - KICI_SANDBOX_NETWORK_ISOLATION (default: true) — RFC1918 + cloud-metadata egress filtering for nested job containers
+* - KICI_RUNNER_DEBUG_STDIO (default: false) — echo the runner child's raw stdio onto the agent's stderr
 * - KICI_EXECUTION_MODE (optional, options: container | bare-metal | firecracker) — override the runner's mode-pick logic
 * - KICI_CONCURRENCY_WAIT_TIMEOUT_MS (default: 3_600_000) — workflow-runner timeout when long-polling for a slot-release follow-up `concurrency.ack`
 * - KICI_AGENT_BETWEEN_JOBS_RESET_COMMAND (optional) — host-reset command run between jobs on a reused agent (fail-open)
@@ -220,10 +232,23 @@ const envDef = defineEnv({
 * - KICI_AGENT_ORPHAN_CLEANUP (default: true) — reap a finished job's leaked process tree (bare-metal); false = only signal the runner child
 * - KICI_AGENT_DRAIN_ON_RESET_FAILURE (default: false) — drain the agent after repeated consecutive reset failures
 */
+/**
+* Env vars the boot-time unknown-KICI_* validator tolerates **only** under
+* `NODE_ENV=test`. `KICI_SKIP_DB_TESTS` is the vitest Postgres harness's
+* opt-out (`scripts/db-test-postgres.ts`), so a suite run with it set must not
+* fail the agent's own config tests. Mirrors the orchestrator's list, which
+* already carries it. Under any other NODE_ENV the allowance is empty, so a
+* production boot with a stray one still fails the validator.
+*/
+const TEST_ONLY_ENV_VARS = ["KICI_SKIP_DB_TESTS"];
 function loadConfig() {
 	const data = envDef.parse();
 	if (!data.scalerManaged && !data.agentToken) validateNoReservedLabels(data.labels, "KICI_LABELS");
-	validateUnknownKiciVars([...envDef.listKnownEnvVars(), ...LOGGER_ENV_VARS]);
+	validateUnknownKiciVars([
+		...envDef.listKnownEnvVars(),
+		...LOGGER_ENV_VARS,
+		...process.env.NODE_ENV === "test" ? TEST_ONLY_ENV_VARS : []
+	]);
 	return {
 		...data,
 		agentId: data.agentId ?? `${hostname()}-${randomUUID().slice(0, 8)}`
@@ -390,10 +415,12 @@ function redactNpmOutput(input, tokens) {
 *
 * `nodeLinker: node-modules` makes berry lay down a real `node_modules` tree
 * (no PnP `.pnp.cjs`), so the agent's packer / restore / sibling-walk /
-* workflow-loader work unchanged. `enableScripts: false` (when a private
-* registry is configured) keeps dependency lifecycle scripts from seeing the
-* synthesized token env vars — the same security model as npm/pnpm/classic
-* `--ignore-scripts`.
+* workflow-loader work unchanged. `enableScripts: false` keeps dependency
+* lifecycle scripts from running at all — for every install, not only one
+* against a private registry — the same security model as npm/pnpm/classic
+* `--ignore-scripts`. An operator opts back in with
+* `KICI_ALLOW_INSTALL_SCRIPTS=true`, which arrives here as
+* `ignoreScripts: false`.
 *
 * Reuses the same `ApplyNpmRegistryConfigArgs` / `ApplyNpmRegistryConfigResult`
 * shapes as the npm overlay so `dep-installer` can pick either by flavor.
@@ -440,8 +467,8 @@ async function applyYarnrcBerryConfig(args) {
 	};
 	const tokenEnv = {};
 	const tokensForRedaction = [];
+	if (args.ignoreScripts !== false) merged.enableScripts = false;
 	if (hasPrivateRegistry) {
-		merged.enableScripts = false;
 		const npmScopes = { ...doc.npmScopes ?? {} };
 		for (let i = 0; i < registries.length; i++) {
 			const reg = registries[i];
@@ -787,9 +814,11 @@ function isAbsoluteRel(rel) {
 * Security: the install runs with an isolated per-invocation cache/store
 * directory to prevent cache poisoning across build jobs — a malicious
 * package.json in one repo cannot taint the cache used by subsequent builds.
-* The same pressure rules out letting lifecycle scripts see synthesized auth
-* env vars — the install runs with `--ignore-scripts` whenever a private
-* registry is configured.
+* The install runs with `--ignore-scripts` for every package manager. A
+* lifecycle script in a committed `package.json` is customer code the agent
+* never agreed to execute: it would run wherever the install runs, which for a
+* step-child install is the process holding the job's secrets. Operators who
+* genuinely need it set `KICI_ALLOW_INSTALL_SCRIPTS=true` on the agent.
 */
 const logger$3 = createLogger({ prefix: "dep-installer" });
 const execFileAsync = promisify(execFile);
@@ -825,9 +854,11 @@ async function detectKiciYarnFlavor(repoRoot, kiciDir) {
 * between build jobs; the directory is removed after installation.
 *
 * If `opts.npmRegistries` / `opts.installEnvSecrets` is provided, a job-scoped
-* `.kici/.npmrc` overlay is synthesized for the install, restored in `finally`,
-* and the install runs with `--ignore-scripts` so lifecycle scripts in a
-* committed `package.json` cannot exfiltrate the synthesized token env vars.
+* `.kici/.npmrc` overlay is synthesized for the install and restored in
+* `finally`.
+*
+* Lifecycle scripts are disabled for every package manager unless the operator
+* set `opts.allowInstallScripts`.
 *
 * @param kiciDir - Path to the `.kici/` directory containing package.json.
 * @param opts    - Optional registry / installEnv / repoRoot configuration.
@@ -849,13 +880,15 @@ async function installDeps(kiciDir, opts = {}) {
 		yarnFlavor
 	});
 	const startTime = Date.now();
-	const hasPrivateRegistry = (opts.npmRegistries?.length ?? 0) > 0 || (opts.installEnvSecrets ? Object.keys(opts.installEnvSecrets).length > 0 : false);
+	const ignoreScripts = opts.allowInstallScripts !== true;
+	const baseEnv = opts.baseEnv ?? process.env;
 	const isBerry = packageManager === PackageManager.Yarn && yarnFlavor === YarnFlavor.Berry;
 	const registryConfig = isBerry ? await applyYarnrcBerryConfig({
 		kiciDir,
 		npmRegistries: opts.npmRegistries,
 		installEnvSecrets: opts.installEnvSecrets,
-		jobIdShort: opts.jobIdShort ?? "00000000"
+		jobIdShort: opts.jobIdShort ?? "00000000",
+		ignoreScripts
 	}) : await applyNpmRegistryConfig({
 		kiciDir,
 		npmRegistries: opts.npmRegistries,
@@ -865,22 +898,26 @@ async function installDeps(kiciDir, opts = {}) {
 	try {
 		if (packageManager === PackageManager.Pnpm) await runPnpmInstall({
 			kiciDir,
-			hasPrivateRegistry,
-			registryConfig
+			ignoreScripts,
+			registryConfig,
+			baseEnv
 		});
 		else if (isBerry) await runYarnBerryInstall({
 			kiciDir,
-			registryConfig
+			registryConfig,
+			baseEnv
 		});
 		else if (packageManager === PackageManager.Yarn) await runYarnInstall({
 			kiciDir,
-			hasPrivateRegistry,
-			registryConfig
+			ignoreScripts,
+			registryConfig,
+			baseEnv
 		});
 		else await runNpmInstall({
 			kiciDir,
-			hasPrivateRegistry,
-			registryConfig
+			ignoreScripts,
+			registryConfig,
+			baseEnv
 		});
 	} catch (e) {
 		const tokens = registryConfig.tokensForRedaction;
@@ -890,8 +927,8 @@ async function installDeps(kiciDir, opts = {}) {
 	} finally {
 		await registryConfig.cleanup();
 	}
-	if (packageManager === PackageManager.Pnpm && await kiciHasLocalProtocolDeps(kiciDir)) await buildWorkspaceClosure(repoRoot);
-	if (packageManager === PackageManager.Yarn) await buildYarnWorkspaceClosure(repoRoot, kiciDir, yarnFlavor);
+	if (packageManager === PackageManager.Pnpm && await kiciHasLocalProtocolDeps(kiciDir)) await buildWorkspaceClosure(repoRoot, baseEnv);
+	if (packageManager === PackageManager.Yarn) await buildYarnWorkspaceClosure(repoRoot, kiciDir, yarnFlavor, baseEnv);
 	const durationMs = Date.now() - startTime;
 	process.stderr.write(`[dep-installer:trace] install complete: ${durationMs}ms\n`);
 	logger$3.info("Deps installed inline", {
@@ -899,20 +936,26 @@ async function installDeps(kiciDir, opts = {}) {
 		durationMs
 	});
 }
-/** Build the Node binary directory onto PATH so spawned tools find `node`. */
-function envWithNodeOnPath(extraEnv, nodeDir) {
-	const { NODE_ENV: _NODE_ENV, ...restEnv } = process.env;
+/**
+* Build the Node binary directory onto PATH so spawned tools find `node`.
+*
+* `baseEnv` is the caller's declared environment for the subprocess. It
+* defaults to `process.env` because inside the runner child that IS the
+* sanitized job environment; an agent-process caller passes a sanitized base.
+*/
+function envWithNodeOnPath(extraEnv, nodeDir, baseEnv = process.env) {
+	const { NODE_ENV: _NODE_ENV, ...restEnv } = baseEnv;
 	return {
 		...restEnv,
 		...extraEnv,
-		PATH: `${nodeDir}${process.platform === "win32" ? ";" : ":"}${process.env.PATH ?? ""}`
+		PATH: `${nodeDir}${process.platform === "win32" ? ";" : ":"}${restEnv.PATH ?? ""}`
 	};
 }
 /** Run `npm install` in `.kici/` with an isolated cache directory. */
 async function runNpmInstall(args) {
 	const { npmCliPath, nodeExe, nodeDir } = resolveNpm();
 	const { path: cacheDir, cleanup } = await makeTempDir("npm-cache");
-	const env = envWithNodeOnPath(args.registryConfig.extraEnv, nodeDir);
+	const env = envWithNodeOnPath(args.registryConfig.extraEnv, nodeDir, args.baseEnv);
 	const buildArgs = (...prefix) => {
 		const a = [
 			...prefix,
@@ -922,7 +965,7 @@ async function runNpmInstall(args) {
 			"--no-audit",
 			"--no-fund"
 		];
-		if (args.hasPrivateRegistry) a.push("--ignore-scripts");
+		if (args.ignoreScripts) a.push("--ignore-scripts");
 		return a;
 	};
 	try {
@@ -951,7 +994,7 @@ async function runPnpmInstall(args) {
 	await assertPnpmAvailable();
 	const { nodeDir } = resolveNpm();
 	const { path: storeDir, cleanup } = await makeTempDir("pnpm-store");
-	const env = envWithNodeOnPath(args.registryConfig.extraEnv, nodeDir);
+	const env = envWithNodeOnPath(args.registryConfig.extraEnv, nodeDir, args.baseEnv);
 	const argv = [
 		"install",
 		`--config.store-dir=${storeDir}`,
@@ -960,7 +1003,7 @@ async function runPnpmInstall(args) {
 		"--config.side-effects-cache=false",
 		PNPM_IGNORE_BUILD_GATE_ARG
 	];
-	if (args.hasPrivateRegistry) argv.push("--ignore-scripts");
+	if (args.ignoreScripts) argv.push("--ignore-scripts");
 	try {
 		process.stderr.write(`[dep-installer:trace] running: pnpm ${argv.join(" ")}\n`);
 		await execFileAsync("pnpm", argv, {
@@ -974,7 +1017,7 @@ async function runPnpmInstall(args) {
 	}
 }
 /** Pure: argv for `yarn install` with an isolated cache folder. */
-function buildYarnInstallArgs(cacheDir, hasPrivateRegistry) {
+function buildYarnInstallArgs(cacheDir, ignoreScripts) {
 	const a = [
 		"install",
 		"--cache-folder",
@@ -982,7 +1025,7 @@ function buildYarnInstallArgs(cacheDir, hasPrivateRegistry) {
 		"--non-interactive",
 		"--no-progress"
 	];
-	if (hasPrivateRegistry) a.push("--ignore-scripts");
+	if (ignoreScripts) a.push("--ignore-scripts");
 	return a;
 }
 /**
@@ -997,8 +1040,8 @@ async function runYarnInstall(args) {
 	await assertYarnAvailable();
 	const { nodeDir } = resolveNpm();
 	const { path: cacheDir, cleanup } = await makeTempDir("yarn-cache");
-	const env = envWithNodeOnPath(args.registryConfig.extraEnv, nodeDir);
-	const argv = buildYarnInstallArgs(cacheDir, args.hasPrivateRegistry);
+	const env = envWithNodeOnPath(args.registryConfig.extraEnv, nodeDir, args.baseEnv);
+	const argv = buildYarnInstallArgs(cacheDir, args.ignoreScripts);
 	try {
 		process.stderr.write(`[dep-installer:trace] running: yarn ${argv.join(" ")}\n`);
 		await execFileAsync("yarn", argv, {
@@ -1028,7 +1071,7 @@ async function runYarnBerryInstall(args) {
 	await assertYarnAvailable();
 	const { nodeDir } = resolveNpm();
 	const env = {
-		...envWithNodeOnPath(args.registryConfig.extraEnv, nodeDir),
+		...envWithNodeOnPath(args.registryConfig.extraEnv, nodeDir, args.baseEnv),
 		COREPACK_ENABLE_DOWNLOAD_PROMPT: "0"
 	};
 	const argv = buildYarnBerryInstallArgs();
@@ -1059,11 +1102,11 @@ async function assertYarnAvailable() {
 * Deep cross-sibling build chains may build out of strict topological order —
 * real `.kici` closures are shallow.
 */
-async function buildYarnWorkspaceClosure(repoRoot, kiciDir, yarnFlavor) {
+async function buildYarnWorkspaceClosure(repoRoot, kiciDir, yarnFlavor, baseEnv) {
 	const siblings = await collectInRepoSiblings(repoRoot, kiciDir, resolveYarnNodeModulesRoot(repoRoot, kiciDir));
 	if (siblings.length === 0) return;
 	const { nodeDir } = resolveNpm();
-	const env = envWithNodeOnPath({}, nodeDir);
+	const env = envWithNodeOnPath({}, nodeDir, baseEnv);
 	for (const rel of [...siblings].reverse()) {
 		const sibDir = join(repoRoot, rel);
 		if (!await siblingHasBuildScript(sibDir)) continue;
@@ -1107,9 +1150,9 @@ async function siblingHasBuildScript(sibDir) {
 * the subprocess stderr/stdout is folded into the thrown error so the job's
 * failure message names the real cause instead of a bare "Command failed".
 */
-async function buildWorkspaceClosure(repoRoot) {
+async function buildWorkspaceClosure(repoRoot, baseEnv) {
 	const { nodeDir } = resolveNpm();
-	const env = envWithNodeOnPath({}, nodeDir);
+	const env = envWithNodeOnPath({}, nodeDir, baseEnv);
 	const argv = [
 		"--filter",
 		"{.kici}^...",

package/dist/provenance/statement-builder.d.ts

@@ -52,27 +52,38 @@ export interface LocalBuildContext {
     repository: string;
     ref: string;
     sha: string | null;
+    /**
+     * The token's `workflow_ref` claim (`<name>@<sha>`) when the orchestrator
+     * supplied one. NOT a global workflow's clone ref — those are never equal,
+     * and comparing them is what a cross-check would have failed on.
+     */
     workflowRef: string;
     runId: string;
     jobId: string;
     orgId?: string;
     sourceOrigin?: SourceOrigin;
+    /** Informational source provider, mirroring the live builder's `provider`. */
+    provider?: string;
+    /** The orchestrator's provenance issuer, for the `builder.id`. */
+    issuer: string;
     /**
-     * Platform provenance issuer for the `builder.id`. The agent does not always
-     * know it at build time (the orchestrator may be disconnected — that is why
-     * the mint deferred), so it is best-effort; an empty string yields a
-     * `/orchestrator/unknown` builder id. This field is not verification
-     * load-bearing for a deferred bundle: the later token binds to the frozen
-     * statement by hash, not by field-for-field cross-check.
+     * The orchestrator instance id, for the `builder.id`. Absent when the
+     * orchestrator sent no provenance context, which yields the honest
+     * `/orchestrator/unknown` the local guess has always produced.
      */
-    issuer: string;
+    orchestratorId?: string;
 }
 /**
  * Build a frozen SLSA v1.0 provenance statement from agent-local job context,
  * for a deferred attestation (no minted identity token yet). Marks
  * `attestationOrigin: 'deferred'` in the internal parameters. The caller
  * DSSE-signs the returned statement immediately and computes its statement hash
- * — the binding the later OIDC mint commits to (truth-contract property 2).
+ * — one of the two bindings the later OIDC mint commits to.
+ *
+ * Emits the same fields `buildProvenanceStatement` emits, so a statement frozen
+ * from an orchestrator-supplied context is field-for-field what a live mint
+ * would have produced. That is what lets the orchestrator cross-check the
+ * statement against its own run row before signing anything that commits to it.
  */
 export declare function buildLocalProvenanceStatement(input: {
     context: LocalBuildContext;