@starci/hfs 4.0.9 → 4.0.10

package/runtime/scripts/api/fs/lib.mjs

@@ -12,3 +12,9 @@ export function unlinkOnly(p) {
   try { fs.unlinkSync(p); } catch { try { fs.rmdirSync(p); } catch { /* verified below */ } }
   try { fs.lstatSync(p); return false; } catch (error) { return error?.code === 'ENOENT'; }
 }
+
+/** Construct an archive-reader refusal with its existing error code. */
+export const zipRefuse = (message, code = 'zip-corrupt') => Object.assign(new Error(message), { code });
+
+/** Relative ZIP entry names exclude traversal, drive roots and control characters. */
+export const validZipName=name=>Boolean(name)&&!name.startsWith('/')&&!/^[A-Za-z]:/.test(name)&&!/[\0\r\n\\]/.test(name)&&!name.split('/').includes('..');

package/runtime/scripts/api/git/lib.mjs

@@ -6,6 +6,7 @@
 // caller's runner into {ok, stdout, stderr}. Only the call files beside this one import it: each names one git verb
 // (diff.mjs, ls-files.mjs, worktree-*.mjs, ...), and a caller folds the spawn result it gets back with the pure
 // helpers of scripts/lib/git.mjs (gitResultOf, gitOutputOf).
+import { assertMutationFence } from '../../lib/mutation-fence.mjs';
 import { spawnSync } from 'node:child_process';
 import { withoutGitLocalEnv } from '../../lib/git.mjs';
 
@@ -16,6 +17,7 @@ import { withoutGitLocalEnv } from '../../lib/git.mjs';
  * ERR_UNKNOWN_ENCODING, so it reaches spawnSync as encoding:null (Buffer output either way).
  */
 export const gitSpawn = (file, args, options = {}) => {
+  assertMutationFence({ kind: 'git-effect', args });
   const spawn = { encoding: 'utf8', windowsHide: true, ...options };
   if (spawn.encoding === 'buffer') spawn.encoding = null;
   return spawnSync(file, args, spawn);

package/runtime/scripts/api/node/lib.mjs

@@ -0,0 +1,14 @@
+// scripts/api/node/lib.mjs — the runner of the runtime's own scripts as child processes: the node binary that runs this
+// process (process.execPath), a hidden window, utf8 text. The call files beside it (run-script.mjs, syntax-check.mjs,
+// run-node.mjs, spawn-node.mjs, exec-node.mjs) each name one use; nothing outside scripts/api/node imports this runner.
+import { assertMutationFence } from '../../lib/mutation-fence.mjs';
+import { execFile, spawn, spawnSync } from 'node:child_process';
+
+/** `node <args>` with this process's node binary, waited for; options pass through last (cwd, stdio, env, timeout, maxBuffer, input). */
+export const nodeSpawn = (args, options = {}) => { assertMutationFence({ kind: 'node-effect', args }); return spawnSync(process.execPath, args, { encoding: 'utf8', windowsHide: true, ...options }); };
+
+/** `node <args>` with this process's node binary, started and not waited for: the ChildProcess (detached, stdio, env pass through). */
+export const nodeStart = (args, options = {}) => { assertMutationFence({ kind: 'node-effect', args }); return spawn(process.execPath, args, { windowsHide: true, ...options }); };
+
+/** `node <args>` with this process's node binary, waited for without blocking the thread: callback(error, stdout, stderr). */
+export const nodeExecFile = (args, options, callback) => { assertMutationFence({ kind: 'node-effect', args }); return execFile(process.execPath, args, { encoding: 'utf8', windowsHide: true, ...options }, callback); };

package/runtime/scripts/api/node/spawn-node.mjs

@@ -0,0 +1,6 @@
+// spawn-node.mjs — `node <args>` with this process's node binary, started and not waited for: a long-running runtime
+// process (a server, an engine, a detached helper). Returns the ChildProcess.
+import { nodeStart } from './lib.mjs';
+
+/** Starts `node <args>`; options (cwd, env, stdio, detached) pass through. */
+export const spawnNode = (args, options = {}) => nodeStart(args, options);

package/runtime/scripts/api/process/lib.mjs

@@ -0,0 +1,111 @@
+// scripts/api/process/lib.mjs — what the process call files beside it share: the spawn options every child of the
+// runtime carries. The call files (process-list.mjs, kill-tree.mjs, run-shell.mjs, spawn-detached.mjs, set-priority.mjs,
+// hide-child-windows.mjs, ...) each name one use of the host's process table or a child process.
+
+/**
+ * `list` with windowsHide: true added to its options argument. `hasArgv`:
+ * the call's second argument may be an argv array (spawn, execFile) rather
+ * than options (exec). An explicit windowsHide (true or false) is kept.
+ */
+export function withWindowsHide(list, hasArgv) {
+  const out = [...list];
+  let slot = 1;
+  if (hasArgv && (Array.isArray(out[1]) || (out[1] == null && out.length > 2))) slot = 2;
+  const options = out[slot];
+  if (options == null) out.splice(slot, out.length > slot ? 1 : 0, { windowsHide: true });
+  else if (typeof options === 'function') out.splice(slot, 0, { windowsHide: true });
+  else if (typeof options === 'object' && !('windowsHide' in options)) out[slot] = { ...options, windowsHide: true };
+  return out;
+}
+
+// ---- the host process table (process-list.mjs, process-list-async.mjs) ------------------------------------------
+
+const psQuote = (s) => String(s).replace(/'/g, "''");
+
+/** The PowerShell script of one process-table read: Win32_Process rows (optionally filtered), with CPU when asked. */
+export function processListScript({ where = null, cmdMax = 4000, cpu = false } = {}) {
+  const filter = where ? ` -Filter '${psQuote(where)}'` : '';
+  return [
+    ...(cpu ? ['$perf = @{}', 'Get-CimInstance Win32_PerfFormattedData_PerfProc_Process | ForEach-Object { if ($_.IDProcess -gt 0) { $perf[[int]$_.IDProcess] = [double]$_.PercentProcessorTime } }'] : []),
+    `Get-CimInstance Win32_Process${filter} | ForEach-Object { $c = [string]$_.CommandLine; [pscustomobject]@{ pid = [int]$_.ProcessId; ppid = [int]$_.ParentProcessId; name = [string]$_.Name; exe = [string]$_.ExecutablePath;`,
+    `  cmd = $c.Substring(0, [Math]::Min(${Number(cmdMax) || 4000}, $c.Length)); ws = [int64]$_.WorkingSetSize;`,
+    `  created = $(if ($_.CreationDate) { ([DateTimeOffset]$_.CreationDate).ToUnixTimeMilliseconds() } else { 0 })${cpu ? '; cpu = $perf[[int]$_.ProcessId]' : ''} } } | ConvertTo-Json -Compress`,
+  ].join('\n');
+}
+
+/** The rows of the PowerShell read's JSON (one object or an array). */
+export const processRowsOfJson = (text) => {
+  const t = String(text ?? '').trim();
+  const v = t ? JSON.parse(t) : [];
+  return (Array.isArray(v) ? v : [v]).map((p) => ({ ...p, pid: Number(p.pid), ppid: Number(p.ppid), cmd: String(p.cmd ?? '') }));
+};
+
+/** The rows of `ps -eo pid=,ppid=,comm=,args=` (exe/created/ws are null there). */
+export const processRowsOfPs = (text, cmdMax = 4000) => String(text ?? '').split(/\r?\n/).map((line) => /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/.exec(line)).filter(Boolean)
+  .map((m) => ({ pid: Number(m[1]), ppid: Number(m[2]), name: m[3].split('/').pop(), exe: null, cmd: m[4].slice(0, cmdMax), created: null, ws: null }));
+
+// ---- the environment of other processes (process-env.mjs) -------------------------------------------------------
+
+// Windows keeps a process's environment block in its PEB: PEB.ProcessParameters (+0x20) -> Environment (+0x80) and
+// EnvironmentSize (+0x3F0), x64 only. A same-user process opens with PROCESS_QUERY_INFORMATION | PROCESS_VM_READ (0x0410).
+export const PROCESS_ENV_NATIVE = `
+using System;
+using System.Collections.Generic;
+using System.Runtime.InteropServices;
+using System.Text;
+public static class StarciProcessEnv {
+  [StructLayout(LayoutKind.Sequential)] struct PBI { public IntPtr Reserved1; public IntPtr PebBaseAddress; public IntPtr Reserved2a; public IntPtr Reserved2b; public IntPtr UniqueProcessId; public IntPtr Reserved3; }
+  [DllImport("ntdll.dll")] static extern int NtQueryInformationProcess(IntPtr h, int cls, ref PBI pbi, int len, out int ret);
+  [DllImport("kernel32.dll")] static extern bool ReadProcessMemory(IntPtr h, IntPtr addr, byte[] buf, IntPtr size, out IntPtr read);
+  [DllImport("kernel32.dll")] static extern IntPtr OpenProcess(int access, bool inherit, int pid);
+  [DllImport("kernel32.dll")] static extern bool CloseHandle(IntPtr h);
+  [DllImport("kernel32.dll")] static extern bool IsWow64Process(IntPtr h, out bool wow);
+  static byte[] Read(IntPtr h, IntPtr addr, int size) {
+    var buf = new byte[size]; IntPtr n;
+    if (!ReadProcessMemory(h, addr, buf, (IntPtr)size, out n) || (int)n != size) return null;
+    return buf;
+  }
+  public static Dictionary<string, string> Env(int pid) {
+    var h = OpenProcess(0x0410, false, pid);
+    if (h == IntPtr.Zero) return null;
+    try { return EnvHandle(h); } finally { CloseHandle(h); }
+  }
+  public static Dictionary<string, string> EnvHandle(IntPtr h) {
+      bool wow; if (IsWow64Process(h, out wow) && wow) return null;
+      var pbi = new PBI(); int ret;
+      if (NtQueryInformationProcess(h, 0, ref pbi, Marshal.SizeOf(pbi), out ret) != 0) return null;
+      var peb = Read(h, pbi.PebBaseAddress + 0x20, 8); if (peb == null) return null;
+      var parameters = (IntPtr)BitConverter.ToInt64(peb, 0);
+      var envPtr = Read(h, parameters + 0x80, 8); if (envPtr == null) return null;
+      var sizeBuf = Read(h, parameters + 0x3F0, 8); if (sizeBuf == null) return null;
+      long size = BitConverter.ToInt64(sizeBuf, 0);
+      if (size <= 0 || size > 4 * 1024 * 1024) return null;
+      var block = Read(h, (IntPtr)BitConverter.ToInt64(envPtr, 0), (int)size); if (block == null) return null;
+      var d = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+      foreach (var entry in Encoding.Unicode.GetString(block).Split('\\0')) {
+        if (entry.Length == 0) continue;
+        int i = entry.IndexOf('=', 1); if (i < 0) continue;
+        d[entry.Substring(0, i)] = entry.Substring(i + 1);
+      }
+      return d;
+  }
+}`;
+
+/** The PowerShell script reading `names` from the environment of `pids` (every process when null): JSON [{pid, readable, values}]. */
+export function processEnvScript({ names, pids = null }) {
+  const wanted = JSON.stringify([...names].map(String));
+  const ids = pids ? `@(${[...pids].map((p) => Number(p)).filter(Number.isInteger).join(',')})` : '(Get-Process).Id';
+  return [
+    `Add-Type -TypeDefinition @'${PROCESS_ENV_NATIVE}\n'@ -Language CSharp`,
+    `$names = '${psQuote(wanted)}' | ConvertFrom-Json`,
+    `$rows = foreach ($id in ${ids}) { $e = [StarciProcessEnv]::Env([int]$id); $v = [ordered]@{}; foreach ($n in $names) { $v[$n] = if ($null -ne $e -and $e.ContainsKey($n)) { $e[$n] } else { $null } }; [pscustomobject]@{ pid = [int]$id; readable = ($null -ne $e); values = $v } }`,
+    '@($rows) | ConvertTo-Json -Compress -Depth 4',
+  ].join('\n');
+}
+
+/** The rows of that script's JSON. */
+export const processEnvRowsOfJson = (text) => {
+  const t = String(text ?? '').trim();
+  const v = t ? JSON.parse(t) : [];
+  return (Array.isArray(v) ? v : [v]).map((r) => ({ pid: Number(r.pid), readable: r.readable === true, values: r.values ?? {} }));
+};

package/runtime/scripts/api/process/owned-process.mjs

@@ -0,0 +1,78 @@
+// Process-object identity and bounded termination; callers supply custody captured at their own launch.
+import { spawnSync } from 'node:child_process';
+import { PROCESS_ENV_NATIVE } from './lib.mjs';
+import { OWNED_PROCESS_SCHEMA, validProcessIdentity as validIdentity } from '../../lib/process-identity.mjs';
+import { allocationMs } from '../../../engine/config.mjs';
+
+const NATIVE = `
+public static class StarciOwnedProcess {
+  [DllImport("kernel32.dll", SetLastError=true)] static extern IntPtr OpenProcess(uint access, bool inherit, int pid);
+  [DllImport("kernel32.dll", SetLastError=true)] static extern bool GetProcessTimes(IntPtr h, out long created, out long exited, out long kernel, out long user);
+  [DllImport("kernel32.dll", CharSet=CharSet.Unicode, SetLastError=true)] static extern bool QueryFullProcessImageName(IntPtr h, uint flags, StringBuilder exe, ref int size);
+  [DllImport("kernel32.dll", SetLastError=true)] static extern bool TerminateProcess(IntPtr h, uint code);
+  [DllImport("kernel32.dll", SetLastError=true)] static extern uint WaitForSingleObject(IntPtr h, uint ms);
+  [DllImport("kernel32.dll")] static extern bool CloseHandle(IntPtr h);
+  public static object[] Call(int pid, bool stop, string birth, string image, string ownershipKey, string ownershipValue, uint waitMs) {
+    var h = OpenProcess(0x00101000u | (stop ? 1u : 0u) | (ownershipKey != null ? 0x0410u : 0u), false, pid);
+    if (h == IntPtr.Zero) return new object[] {false, "unknown", "process-open-unverified", null, null, Marshal.GetLastWin32Error()};
+    try {
+      long created, exited, kernel, user; var exe = new StringBuilder(32768); int size = exe.Capacity;
+      if (!GetProcessTimes(h, out created, out exited, out kernel, out user) || !QueryFullProcessImageName(h, 0, exe, ref size))
+        return new object[] {false, "unknown", "process-identity-unreadable", null, null, Marshal.GetLastWin32Error()};
+      var actualBirth = created.ToString(System.Globalization.CultureInfo.InvariantCulture); var actualImage = exe.ToString();
+      if (stop && (actualBirth != birth || !String.Equals(actualImage, image, StringComparison.OrdinalIgnoreCase)))
+        return new object[] {false, "refused", "process-identity-conflict", actualBirth, actualImage, 0};
+      if (!stop && ownershipKey != null) {
+        var environment = StarciProcessEnv.EnvHandle(h);
+        if (environment == null || !environment.ContainsKey(ownershipKey) || environment[ownershipKey] != ownershipValue)
+          return new object[] {false, "unknown", "process-launch-custody-unverified", actualBirth, actualImage, 0};
+      }
+      var first = WaitForSingleObject(h, 0);
+      if (!stop) return first == 258u ? new object[] {true, "captured", "process-handle-live", actualBirth, actualImage, 0}
+        : new object[] {false, "unknown", "process-not-live-at-capture", actualBirth, actualImage, 0};
+      if (first == 0u) return new object[] {true, "gone", "process-handle-signaled", actualBirth, actualImage, 0};
+      if (first != 258u || !TerminateProcess(h, 1))
+        return new object[] {false, "unknown", "process-termination-unverified", actualBirth, actualImage, Marshal.GetLastWin32Error()};
+      return WaitForSingleObject(h, waitMs) == 0u
+        ? new object[] {true, "stopped", "process-handle-signaled", actualBirth, actualImage, 0}
+        : new object[] {false, "unknown", "process-closure-unverified", actualBirth, actualImage, 0};
+    } finally { CloseHandle(h); }
+  }
+}`;
+const quote = (value) => value == null ? '$null' : `'${String(value).replaceAll("'", "''")}'`;
+
+/**
+ * Capture a live process, or stop the exact captured identity on one verified native handle.
+ * Only Windows is qualified; custody, platform, child completion or receipt failures remain refused or unknown.
+ * The capture and stop call files constrain their modes; this engine preserves the supplied identity and raw outcome.
+ */
+export function ownedProcess(pid, { identity = null, ownership = null, waitMs = allocationMs('workerClose.stopVerifyMs'), run = spawnSync, platform = process.platform } = {}) {
+  const base = { schema: OWNED_PROCESS_SCHEMA, pid, ok: false, outcome: 'unknown', identity: identity ?? null };
+  if (platform !== 'win32') return { ...base, reason: 'process-platform-unverified' };
+  if (!Number.isInteger(pid) || pid <= 0 || identity && !validIdentity(identity)
+      || ownership && (typeof ownership.key !== 'string' || !ownership.key || typeof ownership.value !== 'string' || !ownership.value))
+    return { ...base, outcome: 'refused', reason: 'process-custody-required' };
+  if (!Number.isInteger(waitMs) || waitMs <= 0 || waitMs > 60000) return { ...base, outcome: 'refused', reason: 'process-wait-invalid' };
+  const script = [`Add-Type -TypeDefinition @'\n${PROCESS_ENV_NATIVE}\n${NATIVE}\n'@ -Language CSharp`,
+    `$r = [StarciOwnedProcess]::Call(${pid}, $${identity ? 'true' : 'false'}, ${quote(identity?.birth)}, ${quote(identity?.exe)}, ${quote(ownership?.key)}, ${quote(ownership?.value)}, ${waitMs})`,
+    `@{ schema = '${OWNED_PROCESS_SCHEMA}'; pid = ${pid}; ok = $r[0]; outcome = $r[1]; proof = $r[2]; birth = $r[3]; exe = $r[4]; nativeError = $r[5] } | ConvertTo-Json -Compress`].join('\n');
+  let result;
+  try { result = run('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script],
+    { encoding: 'utf8', windowsHide: true, timeout: waitMs + 15000, maxBuffer: 1024 * 1024 }); }
+  catch (error) { return { ...base, reason: 'process-call-incomplete', error: String(error?.message ?? error) }; }
+  if (result?.status !== 0 || result.error || result.signal)
+    return { ...base, reason: 'process-call-incomplete', status: result?.status ?? null, signal: result?.signal ?? null, error: result?.error?.message ?? null };
+  let data;
+  try { data = JSON.parse(String(result.stdout ?? '').trim()); } catch { return { ...base, reason: 'process-receipt-incomplete' }; }
+  const actual = { pid, birth: data?.birth, exe: data?.exe };
+  if (data?.schema !== OWNED_PROCESS_SCHEMA || data.pid !== pid || typeof data.ok !== 'boolean'
+      || !['unknown', 'refused', 'captured', 'stopped', 'gone'].includes(data.outcome) || typeof data.proof !== 'string'
+      || data.ok && (!validIdentity(actual) || identity && (actual.birth !== identity.birth || actual.exe.toLowerCase() !== identity.exe.toLowerCase())
+        || data.proof !== (identity ? 'process-handle-signaled' : 'process-handle-live')
+        || !(identity ? ['gone', 'stopped'] : ['captured']).includes(data.outcome)))
+    return { ...base, reason: 'process-receipt-incomplete' };
+  return { schema: OWNED_PROCESS_SCHEMA, pid, ok: data.ok, outcome: data.outcome, proof: data.proof,
+    identity: identity ?? (validIdentity(actual) ? actual : null), nativeError: data.nativeError ?? null,
+    ...(identity && validIdentity(actual) && (actual.birth !== identity.birth || actual.exe.toLowerCase() !== identity.exe.toLowerCase()) ? { observedIdentity: actual } : {}),
+    ...(data.ok ? {} : { reason: data.proof }) };
+}

package/runtime/scripts/api/process/resolve-real-tool.mjs

@@ -0,0 +1,46 @@
+// resolve-real-tool.mjs - find the host executable behind a StarCi PATH wrapper without ever selecting that wrapper again.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const pathValue = (env) => {
+  const key = Object.keys(env ?? {}).find((name) => name.toLowerCase() === 'path');
+  return key ? String(env[key] ?? '') : '';
+};
+
+const canonical = (value, { platform, realpath }) => {
+  let resolved = path.resolve(value);
+  try { resolved = realpath(resolved); } catch { /* a missing PATH entry stays comparable by its resolved spelling */ }
+  return platform === 'win32' ? resolved.toLowerCase() : resolved;
+};
+
+const executableNames = (program, { env, platform }) => {
+  if (platform !== 'win32' || path.extname(program)) return [program];
+  const extensions = String(env?.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean);
+  const names = [program];
+  for (const extension of extensions) names.push(`${program}${extension}`, `${program}${extension.toLowerCase()}`);
+  return [...new Set(names)];
+};
+
+/** Resolve `program` from PATH while excluding <home>/.starci/bin by canonical directory identity. */
+export function resolveRealTool(program, { env = process.env, home = os.homedir(), platform = process.platform,
+  stat = fs.statSync, realpath = fs.realpathSync.native } = {}) {
+  const name = String(program ?? '');
+  if (!name || path.basename(name) !== name) return null;
+  const delimiter = platform === 'win32' ? ';' : ':';
+  const shimKey = canonical(path.join(home, '.starci', 'bin'), { platform, realpath });
+  const names = executableNames(name, { env, platform });
+  for (const rawEntry of pathValue(env).split(delimiter).filter(Boolean)) {
+    const entry = rawEntry.replace(/^"(.*)"$/, '$1');
+    if (canonical(entry, { platform, realpath }) === shimKey) continue;
+    for (const executable of names) {
+      const candidate = path.join(entry, executable);
+      try {
+        if (stat(candidate).isFile()) {
+          try { return realpath(candidate); } catch { return path.resolve(candidate); }
+        }
+      } catch { /* try the next executable spelling or PATH entry */ }
+    }
+  }
+  return null;
+}

package/runtime/scripts/api/process/run-program.mjs

@@ -0,0 +1,7 @@
+// run-program.mjs — run one declared program argv (`file args`, never a shell), waited for: a UAT policy command of an
+// assisted run (scripts/uat/assisted-runner.mjs), resolved to its file by scripts/uat/launch.mjs launchFor. Returns the
+// spawnSync result {status, stdout, stderr, error, signal} (utf8 text, a hidden window).
+import { spawnSync } from 'node:child_process';
+
+/** Runs `file args`; options (cwd, env, timeout, stdio, input) pass through. */
+export const runProgram = (file, args, options = {}) => spawnSync(file, args, { encoding: 'utf8', windowsHide: true, ...options });

package/runtime/scripts/api/process/stop-owned-process.mjs

@@ -0,0 +1,9 @@
+// The exact-identity stop call; never infer custody from a PID alone.
+import { ownedProcess as call } from './owned-process.mjs';
+import { OWNED_PROCESS_SCHEMA, validProcessIdentity as validIdentity } from '../../lib/process-identity.mjs';
+
+/** Stop only the process object whose immutable birth and executable were captured by its owner; a signaled handle proves closure, not descendant closure. */
+export function stopOwnedProcess(identity, options = {}) {
+  if (!validIdentity(identity)) return { schema: OWNED_PROCESS_SCHEMA, pid: identity?.pid ?? null, ok: false, outcome: 'refused', reason: 'process-custody-required', identity: identity ?? null };
+  return call(identity.pid, { ...options, identity });
+}

package/runtime/scripts/api/sops/decrypt.mjs

@@ -1,20 +1,13 @@
-// decrypt.mjs — one `sops` decryption: the custody reads (scripts/api/sops/exec-env.mjs execEnv) and the test
-// secrets (scripts/uat/test-secret.mjs testSecret). The plaintext stays in this process's memory (stdout over a pipe).
-import os from 'node:os';
-import path from 'node:path';
-import { spawnSync } from 'node:child_process';
-import { resolveSops } from './lib.mjs';
+// decrypt.mjs — the public SOPS file-decrypt call.
+import { runSopsFile } from './lib.mjs';
 
 /**
- * Run `<bin> <args>` (bin null: the sops resolveSops finds) with SOPS_AGE_KEY_FILE defaulted to ~/.starci/master.identity.
- * {status, stdout, stderr, error}; a missing sops is {status: null, error: SOPS_MISSING}.
+ * Decrypt one custody file from caller-supplied SOPS arguments; the shared file owner requires the caller's original identity selection.
+ * @param {string|null} bin Explicit SOPS executable, or null to use the selected environment's resolver.
+ * @param {string[]} args SOPS arguments forwarded unchanged to the file operation.
+ * @param {object} options Identity, invocation, environment and capture options owned by runSopsFile.
+ * @returns {{status: number|null, stdout: string|null, stderr: string|null, error: Error|null}} The observed child result or typed identity refusal.
  */
-export function decrypt(bin, args, { env = process.env, cwd = undefined, maxBuffer = 16 * 1024 * 1024, timeout = undefined } = {}) {
-  const exe = bin ?? resolveSops(env);
-  if (!exe) return { status: null, stdout: '', stderr: '', error: Object.assign(new Error('sops is not installed (Windows: winget install Mozilla.SOPS)'), { code: 'SOPS_MISSING' }) };
-  const r = spawnSync(exe, args, {
-    cwd, encoding: 'utf8', windowsHide: true, maxBuffer, timeout,
-    env: { ...env, SOPS_AGE_KEY_FILE: env.SOPS_AGE_KEY_FILE || path.join(os.homedir(), '.starci', 'master.identity') },
-  });
-  return { status: r.status, stdout: r.stdout, stderr: r.stderr, error: r.error ?? null };
+export function decrypt(bin, args, options = {}) {
+  return runSopsFile(bin, args, 'decrypt', options);
 }

package/runtime/scripts/api/sops/lib.mjs

@@ -1,9 +1,12 @@
-// scripts/api/sops/lib.mjs — what the sops call files beside it share: the input type a custody file's name states.
+// scripts/api/sops/lib.mjs — shared file formats, identity admission and SOPS child capture.
 // Custody members are committed as `<name>.<fmt>.enc`; sops infers a format from the LAST extension, so `.enc` reads as
 // binary and every read states the format (--input-type). The call files (decrypt.mjs, encrypt.mjs, exec-env.mjs) each
 // name one sops use.
 import fs from 'node:fs';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { readSecretBytes, CREDENTIAL_FILE_MAX_BYTES, sopsIdentityEnv } from '../../../engine/secrets.mjs';
+import { selectedAgeEnvelope } from '../../lib/sops-envelope.mjs';
 
 const FORMATS = { yaml: 'yaml', yml: 'yaml', json: 'json', env: 'dotenv', dotenv: 'dotenv' };
 
@@ -19,17 +22,234 @@ export function custodyInputType(file, override) {
   return type;
 }
 
-/** The sops binary: PATH, then winget's Links and Packages (spawn without a shell ignores PATHEXT). */
-export function resolveSops(env = process.env) {
-  const win = process.platform === 'win32';
-  const names = win ? ['sops.exe', 'sops'] : ['sops'];
+/** Resolve SOPS from PATH and WinGet. Consumers select PATHEXT names and the full package tree for their launcher. */
+export function resolveSops(env = process.env, { platform = process.platform, pathext = false, wingetPackageTree = false, filesystem = fs } = {}) {
+  const win = platform === 'win32';
+  const paths = win ? path.win32 : path.posix;
+  const names = win
+    ? (pathext ? String(env.PATHEXT || '.EXE;.CMD;.BAT').split(';').filter(Boolean).map((ext) => `sops${ext}`) : ['sops.exe', 'sops'])
+    : ['sops'];
   const dirs = String(env.PATH ?? '').split(win ? ';' : ':').filter(Boolean);
   if (win && env.LOCALAPPDATA) {
-    const winget = path.join(env.LOCALAPPDATA, 'Microsoft', 'WinGet');
-    dirs.push(path.join(winget, 'Links'));
-    const packages = path.join(winget, 'Packages');
-    try { for (const e of fs.readdirSync(packages)) if (/sops/i.test(e)) dirs.push(path.join(packages, e)); } catch { /* none */ }
+    const winget = paths.join(env.LOCALAPPDATA, 'Microsoft', 'WinGet');
+    dirs.push(paths.join(winget, 'Links'));
+    const packages = paths.join(winget, 'Packages');
+    try {
+      for (const entry of filesystem.readdirSync(packages)) {
+        if (!wingetPackageTree && !/sops/i.test(entry)) continue;
+        const directory = paths.join(packages, entry);
+        dirs.push(directory);
+        if (wingetPackageTree) {
+          try {
+            for (const nested of filesystem.readdirSync(directory, { withFileTypes: true })) {
+              if (nested.isDirectory()) dirs.push(paths.join(directory, nested.name));
+            }
+          } catch { /* unreadable package */ }
+        }
+      }
+    } catch { /* no WinGet packages */ }
+  }
+  for (const directory of dirs) for (const name of names) {
+    const file = paths.join(directory, name);
+    try { if (filesystem.statSync(file).isFile()) return file; } catch { /* next candidate */ }
   }
-  for (const dir of dirs) for (const n of names) { const f = path.join(dir, n); try { if (fs.statSync(f).isFile()) return f; } catch { /* next */ } }
   return null;
 }
+
+/**
+ * Select the caller's identity once, then run the encrypt/decrypt file action through its admitted SOPS path.
+ * Inline selection delegates the unchanged request to runSelectedSops; original FILE and recipient-only modes retain their existing child transport.
+ * @param {string|null} bin Explicit SOPS executable, or null to resolve it from the selected environment.
+ * @param {string[]} args The caller's SOPS argument array; no private identity is added to it.
+ * @param {'encrypt'|'decrypt'} operation The public file action, which owns identity requirements and capture defaults.
+ * @param {object} options Original identity, selected invocation ports, environment, cwd, timeout and maxBuffer.
+ * @returns {{status: number|null, stdout: string|null, stderr: string|null, error: Error|null}} The unchanged child result or typed prelaunch refusal.
+ */
+export function runSopsFile(bin, args, operation, options = {}) {
+  const { identity = null, invocation = null, env = process.env, cwd = undefined } = options;
+  let maxBuffer, timeout;
+  if (operation === 'decrypt') ({ maxBuffer = 16 * 1024 * 1024, timeout = undefined } = options);
+  else ({ timeout = undefined, maxBuffer = 1024 * 1024 } = options);
+  const selected = sopsIdentityEnv(env, operation === 'decrypt' ? { identity, required: true } : { identity });
+  if (selected.error?.identityRefusal === 'inline-context-unqualified') return runSelectedSops(bin, { operation, args }, { selection: selected, invocation, env, cwd, maxBuffer, timeout });
+  if (selected.error) return { status: null, stdout: '', stderr: '', error: selected.error };
+  const exe = bin ?? resolveSops(selected.env);
+  if (!exe) return { status: null, stdout: '', stderr: '', error: Object.assign(new Error('sops is not installed (Windows: winget install Mozilla.SOPS)'), { code: 'SOPS_MISSING' }) };
+  const r = spawnSync(exe, args, {
+    encoding: 'utf8', windowsHide: true, maxBuffer, timeout, env: selected.env,
+    ...(operation === 'decrypt' ? { cwd } : { stdio: ['ignore', 'pipe', 'pipe'] }),
+  });
+  return { status: r.status, stdout: r.stdout, stderr: r.stderr, error: r.error ?? null };
+}
+
+const SELECTED_SOPS_VERSIONS = new Set(['3.13.2', '3.13.3']);
+const SELECTED_AGE_VERSIONS = new Set(['1.2.1', '1.3.1']);
+const IDENTITY_TIMEOUT_MS = 20_000;
+const CONTROLLED_ENV = new Set(['SOPS_AGE_KEY', 'SOPS_AGE_KEY_FILE', 'SOPS_AGE_KEY_CMD', 'SOPS_AGE_SSH_PRIVATE_KEY_FILE', 'SOPS_AGE_SSH_PRIVATE_KEY_CMD', 'SOPS_AGE_RECIPIENT', 'SOPS_KEYSERVICE', 'SOPS_ENABLE_LOCAL_KEYSERVICE', 'SOPS_DECRYPTION_ORDER', 'SOPS_KMS_ARN', 'SOPS_GCP_KMS_IDS', 'SOPS_HUAWEICLOUD_KMS_IDS', 'SOPS_AZURE_KEYVAULT_URLS', 'SOPS_VAULT_URIS', 'SOPS_PGP_FP', 'SOPS_AGE_RECIPIENTS', 'HOME', 'USERPROFILE', 'APPDATA', 'XDG_CONFIG_HOME']);
+
+/** Construct only the child map; empty desktop roots make Go return directory errors, not fallback paths. */
+export function isolatedSopsEnv(env, inlineName = 'SOPS_AGE_KEY') {
+  const out = Object.fromEntries(Object.entries(env).filter(([name]) => !CONTROLLED_ENV.has(name.toUpperCase())));
+  out.HOME = ''; out.USERPROFILE = ''; out.APPDATA = ''; out.XDG_CONFIG_HOME = '';
+  if (inlineName !== null) out.SOPS_AGE_KEY = env[inlineName];
+  return out;
+}
+
+const held = reason => ({ status: null, stdout: '', stderr: '', error: Object.assign(new Error(`SOPS selected identity [${reason}]: the selected invocation was not qualified`), { name: 'SopsIdentityRefusal', identityRefusal: reason }) });
+const nativeFile = file => {
+  if (typeof file !== 'string' || !path.isAbsolute(file) || /\.(?:[cm]?js|cmd|bat|ps1|sh)$/i.test(file)) return false;
+  let fd;
+  try {
+    const before = fs.lstatSync(file);
+    if (!before.isFile() || before.isSymbolicLink()) return false;
+    fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    const stat = fs.fstatSync(fd), head = Buffer.alloc(64);
+    if (!stat.isFile() || before.dev !== stat.dev || before.ino !== stat.ino || fs.readSync(fd, head, 0, head.length, 0) < 20) return false;
+    if (process.platform === 'win32' && head.toString('ascii', 0, 2) === 'MZ') {
+      const offset = head.readUInt32LE(60), pe = Buffer.alloc(6);
+      return offset >= 64 && offset + pe.length <= stat.size && fs.readSync(fd, pe, 0, pe.length, offset) === pe.length && pe.toString('ascii', 0, 4) === 'PE\0\0';
+    }
+    if (process.platform === 'linux') return head.subarray(0, 4).equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46]));
+    if (process.platform === 'darwin') return new Set([0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe, 0xcafebabe, 0xbebafeca, 0xcafebabf, 0xbfbafeca]).has(head.readUInt32BE(0));
+    return false;
+  } catch { return false; }
+  finally { if (fd !== undefined) { try { fs.closeSync(fd); } catch { /* no private result or success credit */ } } }
+};
+const auditAbsent = cwd => {
+  try { fs.lstatSync(path.resolve(cwd ?? process.cwd(), '/etc/sops/audit.yaml')); return false; }
+  catch (error) { return error.code === 'ENOENT'; }
+};
+const captured = r => r && r.status === 0 && r.signal == null && !r.error && Buffer.isBuffer(r.stdout) && Buffer.isBuffer(r.stderr);
+const decoded = bytes => new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+const ownedRequest = request => {
+  if (request.operation === 'seal') {
+    const p = request.params;
+    if (!p || !Array.isArray(p.recipients) || p.recipients.length !== 1 || typeof p.filenameOverride !== 'string' || !p.filenameOverride || (typeof p.plaintext !== 'string' && !Buffer.isBuffer(p.plaintext)) || Buffer.byteLength(p.plaintext) > CREDENTIAL_FILE_MAX_BYTES) return null;
+    return { inputType: p.inputType, outputType: p.inputType, file: p.filenameOverride, recipient: p.recipients[0], plaintext: p.plaintext };
+  }
+  const args = request.args;
+  if (!Array.isArray(args) || !['decrypt', '--decrypt', 'encrypt', '--encrypt'].includes(args[0]) || args.some(value => typeof value !== 'string')) return null;
+  if (!args.at(-1) || args.at(-1).startsWith('-')) return null;
+  const flags = {};
+  for (let i = 1; i < args.length - 1; i += 2) {
+    const flag = args[i];
+    if (!['--input-type', '--output-type', '--age'].includes(flag) || Object.hasOwn(flags, flag) || i + 1 >= args.length - 1) return null;
+    flags[flag] = args[i + 1];
+  }
+  if (request.operation === 'decrypt' && (args[0] !== 'decrypt' && args[0] !== '--decrypt' || Object.hasOwn(flags, '--age'))) return null;
+  if (request.operation === 'encrypt' && (args[0] !== 'encrypt' && args[0] !== '--encrypt' || !flags['--age'] || flags['--age'].includes(','))) return null;
+  return { inputType: flags['--input-type'], outputType: flags['--output-type'], file: args.at(-1), recipient: flags['--age'] };
+};
+
+/** The domain composes the existing process owner: invocation={runProgram(file,args,options),resolveRealTool(program,{env})}. No API imports another system. */
+export function runSelectedSops(bin, request, { selection, invocation, env, cwd, maxBuffer, timeout } = {}) {
+  if (selection?.error?.identityRefusal !== 'inline-context-unqualified' || typeof selection.inlineName !== 'string' || !env || typeof env !== 'object') return held('selected-context-missing');
+  const spec = ownedRequest(request);
+  if (!spec || !['binary', 'json', 'yaml', 'dotenv'].includes(spec.inputType) || !['binary', 'json', 'yaml', 'dotenv'].includes(spec.outputType)) return { status: null, stdout: '', stderr: '', error: selection.error };
+  if (!invocation || typeof invocation.runProgram !== 'function' || typeof invocation.resolveRealTool !== 'function') return { status: null, stdout: '', stderr: '', error: selection.error };
+  if (!['win32', 'linux', 'darwin'].includes(process.platform)) return held('unsupported-platform');
+  const key = env[selection.inlineName];
+  if (typeof key !== 'string' || !/^AGE-SECRET-KEY-1[0-9A-Z]+$/.test(key.trim())) return { status: null, stdout: '', stderr: '', error: selection.error };
+  let input, identity, selectedEnv;
+  const captures = [];
+  try {
+    const file = path.resolve(cwd ?? process.cwd(), spec.file);
+    try { input = request.operation === 'seal' ? Buffer.from(spec.plaintext) : readSecretBytes(file); } catch { return held('actual-document-unavailable'); }
+    if (input.length > CREDENTIAL_FILE_MAX_BYTES) return held('document-over-budget');
+    const exe = bin ?? resolveSops(env), age = invocation.resolveRealTool('age-keygen', { env });
+    if (!nativeFile(exe) || !nativeFile(age)) return held('native-tool-unavailable');
+    if (!auditAbsent(cwd)) return held('unsupported-audit-context');
+    const deadline = timeout ?? IDENTITY_TIMEOUT_MS;
+    if (!Number.isInteger(deadline) || deadline < 1 || deadline > 2_147_483_647 || !Number.isInteger(maxBuffer) || maxBuffer < 1) return held('invalid-capture-budget');
+    selectedEnv = isolatedSopsEnv(env, selection.inlineName);
+    const publicEnv = isolatedSopsEnv(env, null);
+    const options = { cwd, env: selectedEnv, shell: false, encoding: 'buffer', windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'], timeout: deadline, maxBuffer };
+    const run = (program, args, bytes, childEnv = selectedEnv) => {
+      const result = invocation.runProgram(program, args, { ...options, env: childEnv, input: bytes });
+      captures.push(result); return result;
+    };
+    const version = run(exe, ['--disable-version-check', '--version'], undefined, publicEnv);
+    const ageVersion = run(age, ['--version'], undefined, publicEnv);
+    if (!captured(version) || !captured(ageVersion) || !SELECTED_SOPS_VERSIONS.has(/^sops\s+([0-9]+\.[0-9]+\.[0-9]+)/.exec(decoded(version.stdout))?.[1]) || !SELECTED_AGE_VERSIONS.has(/^v?([0-9]+\.[0-9]+\.[0-9]+)/.exec(decoded(ageVersion.stdout))?.[1])) return held('unsupported-tool-profile');
+    identity = Buffer.from(key.trim(), 'utf8');
+    const derived = run(age, ['-y'], identity, publicEnv);
+    if (!captured(derived)) return held('recipient-unproven');
+    const recipients = decoded(derived.stdout).trim().split(/\r?\n/);
+    if (recipients.length !== 1 || !/^age1[ac-hj-np-z02-9]+$/.test(recipients[0])) return held('recipient-unproven');
+    const recipient = recipients[0];
+    const decryptArgs = (inputType, outputType) => ['decrypt', '--input-type', inputType, '--output-type', outputType, '--filename-override', file, '--enable-local-keyservice=true', '--decryption-order', 'age'];
+    if (request.operation === 'decrypt') {
+      const envelope = selectedAgeEnvelope(decoded(input), spec.inputType, recipient);
+      if (!envelope.ok) return held(envelope.reason);
+      const result = run(exe, decryptArgs(spec.inputType, spec.outputType), input);
+      if (!captured(result)) return held('selected-decryption-failed');
+      return { status: 0, stdout: decoded(result.stdout), stderr: '', error: null };
+    }
+    if (spec.recipient !== recipient) return held('recipient-mismatch');
+    const args = ['encrypt', '--input-type', spec.inputType, '--output-type', spec.outputType, '--filename-override', file, '--enable-local-keyservice=true', '--age', recipient];
+    const result = run(exe, args, input);
+    if (!captured(result)) return held('selected-encryption-failed');
+    if (result.stdout.length > CREDENTIAL_FILE_MAX_BYTES) return held('document-over-budget');
+    const text = decoded(result.stdout);
+    const envelope = selectedAgeEnvelope(text, spec.outputType, recipient);
+    if (!envelope.ok) return held(envelope.reason);
+    const readback = run(exe, decryptArgs(spec.outputType, spec.inputType), result.stdout);
+    if (!captured(readback)) return held('selected-readback-failed');
+    return { status: 0, stdout: text, stderr: '', error: null };
+  } catch { return held('selected-native-refused'); }
+  finally {
+    identity?.fill(0); input?.fill(0);
+    for (const result of captures) { if (Buffer.isBuffer(result?.stdout)) result.stdout.fill(0); if (Buffer.isBuffer(result?.stderr)) result.stderr.fill(0); }
+    if (selectedEnv) delete selectedEnv.SOPS_AGE_KEY;
+  }
+}
+
+/** One real private capture for an admitted initial request; the installer owns its durable attempt. */
+export function withGeneratedAgeIdentity({ env, cwd, invocation, assertLease, consume } = {}) {
+  const failure = (reason, generated) => ({ ok: false, reason, captureState: generated ? 'unknown' : 'none', effectState: generated ? 'unknown' : 'none' });
+  if (!env || typeof env !== 'object' || !path.isAbsolute(cwd ?? '') || typeof consume !== 'function'
+    || typeof assertLease !== 'function' || typeof invocation?.runProgram !== 'function'
+    || typeof invocation?.resolveRealTool !== 'function') return failure('invalid-request', false);
+  const captures = [];
+  let generated = false, identity;
+  try {
+    const age = invocation.resolveRealTool('age-keygen', { env });
+    if (!nativeFile(age)) return failure('native-tool-unavailable', false);
+    const options = { cwd, env: isolatedSopsEnv(env, null), shell: false, encoding: 'buffer', windowsHide: true,
+      stdio: ['pipe', 'pipe', 'pipe'], timeout: IDENTITY_TIMEOUT_MS, maxBuffer: CREDENTIAL_FILE_MAX_BYTES };
+    const run = (args, input) => {
+      if (assertLease() !== true) throw new Error('initial age lease lost');
+      const result = invocation.runProgram(age, args, { ...options, input });
+      captures.push(result);
+      if (!captured(result) || result.stdout.length > options.maxBuffer || result.stderr.length > options.maxBuffer) throw new Error('initial age capture incomplete');
+      return result;
+    };
+    const version = run(['--version']);
+    if (!SELECTED_AGE_VERSIONS.has(/^v?([0-9]+\.[0-9]+\.[0-9]+)/.exec(decoded(version.stdout))?.[1])) return failure('unsupported-tool-profile', false);
+    if (assertLease() !== true) return failure('lease-lost', false);
+    generated = true;
+    const made = run([]), lines = decoded(made.stdout).trim().split(/\r?\n/);
+    const identities = lines.filter(line => line && !line.startsWith('#'));
+    if (identities.length !== 1 || !/^AGE-SECRET-KEY-1[0-9A-Z]+$/.test(identities[0])
+      || lines.some(line => line.startsWith('#') && !/^# (?:created:|public key:)/.test(line))) return failure('capture-incomplete', true);
+    identity = Buffer.from(identities[0], 'utf8');
+    const derived = run(['-y'], identity), recipients = decoded(derived.stdout).trim().split(/\r?\n/);
+    if (recipients.length !== 1 || !/^age1[ac-hj-np-z02-9]+$/.test(recipients[0])) return failure('recipient-unproven', true);
+    const recipient = recipients[0], declared = lines.filter(line => line.startsWith('# public key:'));
+    if (declared.length !== 1 || declared[0].slice('# public key:'.length).trim() !== recipient || assertLease() !== true) return failure('recipient-unproven', true);
+    const publication = consume(identity, recipient);
+    if (!publication || typeof publication.ok !== 'boolean' || !['none', 'unknown', 'complete'].includes(publication.effectState)) return failure('publication-unknown', true);
+    if (!publication.ok || publication.effectState !== 'complete') return { ok: false, captureState: 'generated', effectState: publication.effectState,
+      reason: 'publication-held' };
+    if (![true, false].includes(publication.created) || !['file-fsync', 'file-and-parent-fsync', 'file-fsync-namespace-unqualified'].includes(publication.durability)) return failure('publication-unknown', true);
+    return { ok: true, captureState: 'generated', effectState: 'complete', created: publication.created,
+      durability: publication.durability, publicRecipient: recipient };
+  } catch { return failure('capture-or-publication-unknown', generated); }
+  finally {
+    identity?.fill(0);
+    for (const result of captures) {
+      if (Buffer.isBuffer(result?.stdout)) result.stdout.fill(0);
+      if (Buffer.isBuffer(result?.stderr)) result.stderr.fill(0);
+    }
+  }
+}