@starci/hfs 4.0.10 → 4.1.0

package/runtime/scripts/api/fs/forbidden-root.mjs

@@ -6,6 +6,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { samePath } from '../../lib/path-key.mjs';
 import { realpathOr } from '../../lib/fs-kind.mjs';
+import { tempRoot } from '../../../engine/temp-root.mjs';
 
 const SKILL_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
 
@@ -37,7 +38,7 @@ function strictlyInsideReal(p, root) {
 export function forbiddenRoot(p, { checkoutsUnder = null, hold } = {}) {
   const resolved = path.resolve(p);
   if (path.parse(resolved).root === resolved || samePath(path.dirname(resolved), resolved)) return 'a filesystem root';
-  for (const [name, dir] of [['the home directory', os.homedir()], ['the temp directory', os.tmpdir()], ['the runtime', SKILL_ROOT],
+  for (const [name, dir] of [['the home directory', os.homedir()], ['the temp directory', os.tmpdir()], ['the configured temp root', tempRoot()], ['the runtime', SKILL_ROOT],
     ['the repository hosting the runtime', path.dirname(SKILL_ROOT)], ['the repositories root', path.dirname(path.dirname(SKILL_ROOT))]]) {
     if (dir && samePath(path.resolve(dir), resolved)) return name;
   }

package/runtime/scripts/api/fs/make-temp-dir.mjs

@@ -0,0 +1,11 @@
+// make-temp-dir.mjs — a fresh temporary directory under the temp root (engine/temp-root.mjs tempRoot).
+import fs from 'node:fs';
+import path from 'node:path';
+import { ensureTempRoot } from './ensure-temp-root.mjs';
+
+/** A new directory `<prefix><random>` under `parent` (default the temp root, ensureTempRoot: TEMP_ROOT_UNUSABLE when it cannot be made), which is created when it is missing. */
+export function makeTempDir(prefix, { env = process.env, parent = undefined } = {}) {
+  const root = parent ?? ensureTempRoot({ env });
+  fs.mkdirSync(root, { recursive: true });
+  return fs.mkdtempSync(path.join(root, prefix));
+}

package/runtime/scripts/api/fs/safe-remove.mjs

@@ -41,7 +41,7 @@ const retrying = (fn, retries) => {
 };
 const removeFile = (p, retries) => retrying(() => {
   try { fs.unlinkSync(p); } catch (error) {
-    if (WIN && (error?.code === 'EPERM' || error?.code === 'EACCES')) { fs.chmodSync(p, 0o666); fs.unlinkSync(p); } else throw error;
+    if (WIN && (error?.code === 'EPERM' || error?.code === 'EACCES')) { fs.chmodSync(p, 0o600); fs.unlinkSync(p); } else throw error;
   }
 }, retries);
 
@@ -65,40 +65,57 @@ export function safeRemove(root, { retries = 5, checkoutsUnder = null, hold } =
   // the root itself or strictly under the root's real path. A link is unlinked above (the link only); any other
   // entry that resolves outside the tree is refused, whatever made it look like a plain entry.
   const rootReal = realpathOr(target);
-  const insideRoot = (p) => { const real = realpathOr(p); if (!real || !rootReal) return false; if (same(real, rootReal)) return true;
-    const rel = path.relative(rootReal, real); return Boolean(rel) && !rel.startsWith('..') && !path.isAbsolute(rel); };
-  const walk = (dir, st, parentReal) => {
-    if (isLinkLike(dir, { parentReal, stat: st })) {
-      if (unlinkOnly(dir)) { out.removed.links += 1; return true; }
-      fail(dir, { code: 'LINK_STUCK', message: 'a link could not be unlinked; nothing above it is removed' });
-      return false;
-    }
-    if (!insideRoot(dir)) {
-      fail(dir, { code: 'OUTSIDE_ROOT', message: `refusing to delete ${dir}: its real path ${realpathOr(dir) ?? '?'} is outside ${rootReal ?? target}` });
-      return false;
-    }
-    if (!st.isDirectory()) {
-      const error = removeFile(dir, retries);
-      if (error) { fail(dir, error); return false; }
-      out.removed.files += 1; return true;
-    }
-    const real = realpathOr(dir);
-    if (!real) { fail(dir, { code: 'REALPATH', message: 'cannot resolve the directory' }); return false; }
-    let entries;
-    try { entries = fs.readdirSync(dir); } catch (error) { fail(dir, error); return false; }
-    let clear = true;
-    for (const name of entries) {
-      const child = path.join(dir, name);
-      let childStat;
-      try { childStat = fs.lstatSync(child); } catch (error) { if (error?.code !== 'ENOENT') { fail(child, error); clear = false; } continue; }
-      if (!walk(child, childStat, real)) clear = false;
-    }
-    if (!clear) return false;
-    const error = retrying(() => fs.rmdirSync(dir), retries);
-    if (error) { fail(dir, error); return false; }
-    out.removed.dirs += 1; return true;
-  };
-  walk(target, st, null);
+  const ctx = { out, fail, retries, rootReal, target };
+  walk(ctx, target, st, null);
   out.ok = !fs.existsSync(target) && (() => { try { fs.lstatSync(target); return false; } catch { return true; } })();
   return out;
 }
+
+function insideRoot({ rootReal }, p) {
+  const real = realpathOr(p);
+  if (!real || !rootReal) return false;
+  if (same(real, rootReal)) return true;
+  const rel = path.relative(rootReal, real);
+  return Boolean(rel) && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+// Removes each child of `dir` (real path `real`); false when any child stays.
+function removeChildren(ctx, dir, entries, real) {
+  let clear = true;
+  for (const name of entries) {
+    const child = path.join(dir, name);
+    let childStat;
+    try { childStat = fs.lstatSync(child); } catch (error) { if (error?.code !== 'ENOENT') { ctx.fail(child, error); clear = false; } continue; }
+    if (!walk(ctx, child, childStat, real)) clear = false;
+  }
+  return clear;
+}
+
+function walkDirectory(ctx, dir) {
+  const { out, fail, retries } = ctx;
+  const real = realpathOr(dir);
+  if (!real) { fail(dir, { code: 'REALPATH', message: 'cannot resolve the directory' }); return false; }
+  let entries;
+  try { entries = fs.readdirSync(dir); } catch (error) { fail(dir, error); return false; }
+  if (!removeChildren(ctx, dir, entries, real)) return false;
+  const error = retrying(() => fs.rmdirSync(dir), retries);
+  if (error) { fail(dir, error); return false; }
+  out.removed.dirs += 1; return true;
+}
+
+function walk(ctx, dir, st, parentReal) {
+  const { out, fail, retries, rootReal, target } = ctx;
+  if (isLinkLike(dir, { parentReal, stat: st })) {
+    if (unlinkOnly(dir)) { out.removed.links += 1; return true; }
+    fail(dir, { code: 'LINK_STUCK', message: 'a link could not be unlinked; nothing above it is removed' });
+    return false;
+  }
+  if (!insideRoot(ctx, dir)) {
+    fail(dir, { code: 'OUTSIDE_ROOT', message: `refusing to delete ${dir}: its real path ${realpathOr(dir) ?? '?'} is outside ${rootReal ?? target}` });
+    return false;
+  }
+  if (st.isDirectory()) return walkDirectory(ctx, dir);
+  const error = removeFile(dir, retries);
+  if (error) { fail(dir, error); return false; }
+  out.removed.files += 1; return true;
+}

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

@@ -7,8 +7,12 @@
 // (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 fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { withoutGitLocalEnv } from '../../lib/git.mjs';
+import { withTempEnv } from '../../../engine/temp-root.mjs';
 
 /**
  * Spawn `file` (the git binary) once with `args`: utf8 text, a hidden window, never a shell.
@@ -20,7 +24,8 @@ 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);
+  // tempChildEnv copies the env (node adds NODE_V8_COVERAGE to the env object it is given: a frozen caller env must not throw under coverage) and points TEMP/TMP/TMPDIR at the temp root
+  return spawnSync(file, args, withTempEnv(spawn));
 };
 
 /**
@@ -42,3 +47,31 @@ export const gitRunner = (git = null) => (args, opts = {}) => {
   const r = git ? git(args, opts) : runGit(args, { timeout: 300_000, maxBuffer: 64 * 1024 * 1024, ...opts });
   return { ok: r?.ok ?? (!r?.error && r?.status === 0), stdout: String(r?.stdout ?? r?.out ?? '').trim(), stderr: String(r?.stderr ?? r?.err ?? r?.error?.message ?? r?.error ?? '').trim() };
 };
+
+let cachedGit;
+const gitPathOf = ({ env, platform, home, exists }) => {
+  const p = platform === 'win32' ? path.win32 : path.posix;
+  const pathKey = Object.keys(env).find((name) => name.toLowerCase() === 'path');
+  const shim = p.join(home, '.starci', 'bin');
+  const same = (a, b) => (platform === 'win32' ? p.resolve(a).toLowerCase() === p.resolve(b).toLowerCase() : p.resolve(a) === p.resolve(b));
+  const binary = platform === 'win32' ? 'git.exe' : 'git';
+  for (const raw of String(pathKey ? env[pathKey] : '').split(platform === 'win32' ? ';' : ':')) {
+    const dir = raw.replace(/^"(.*)"$/, '$1');
+    const file = dir && p.isAbsolute(dir) && !same(dir, shim) ? p.join(dir, binary) : null;
+    if (file && exists(file)) return file;
+  }
+  return null;
+};
+/**
+ * The absolute path of the real git binary, or null: the first PATH directory holding git (git.exe on Windows) that is not
+ * the StarCi shim directory <home>/.starci/bin (a seat's guard shim is never the git the runtime itself runs). A bare name is never
+ * spawned, so a writable directory cannot be reached by name lookup at spawn time. Resolved once per process; options (env,
+ * platform, home, exists) are for a spec and bypass the cache.
+ */
+export const gitExecutable = (options = null) => {
+  if (!options && cachedGit !== undefined) return cachedGit;
+  const { env = process.env, platform = process.platform, home = os.homedir(), exists = (file) => fs.statSync(file, { throwIfNoEntry: false })?.isFile() === true } = options ?? {};
+  const found = gitPathOf({ env, platform, home, exists });
+  if (!options) cachedGit = found;
+  return found;
+};

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

@@ -22,6 +22,18 @@ const executableNames = (program, { env, platform }) => {
   return [...new Set(names)];
 };
 
+const firstExecutableHit = (entry, names, stat, realpath) => {
+  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;
+};
+
 /** 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 } = {}) {
@@ -33,14 +45,8 @@ export function resolveRealTool(program, { env = process.env, home = os.homedir(
   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 */ }
-    }
+    const hit = firstExecutableHit(entry, names, stat, realpath);
+    if (hit) return hit;
   }
   return null;
 }

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

@@ -2,6 +2,7 @@
 // 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';
+import { withTempEnv } from '../../../engine/temp-root.mjs';
 
 /** 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 });
+export const runProgram = (file, args, options = {}) => spawnSync(file, args, withTempEnv({ encoding: 'utf8', windowsHide: true, ...options }));

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

@@ -22,33 +22,50 @@ export function custodyInputType(file, override) {
   return type;
 }
 
+const sopsNames = (env, win, pathext) => {
+  if (!win) return ['sops'];
+  if (!pathext) return ['sops.exe', 'sops'];
+  return String(env.PATHEXT || '.EXE;.CMD;.BAT').split(';').filter(Boolean).map((ext) => `sops${ext}`);
+};
+
+const nestedPackageDirs = (filesystem, paths, directory) => {
+  const dirs = [];
+  try {
+    for (const nested of filesystem.readdirSync(directory, { withFileTypes: true })) {
+      if (nested.isDirectory()) dirs.push(paths.join(directory, nested.name));
+    }
+  } catch { /* unreadable package */ }
+  return dirs;
+};
+
+const wingetPackageDirs = (filesystem, paths, packages, wingetPackageTree) => {
+  const dirs = [];
+  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) dirs.push(...nestedPackageDirs(filesystem, paths, directory));
+    }
+  } catch { /* no WinGet packages */ }
+  return dirs;
+};
+
+const wingetDirs = (filesystem, paths, env, wingetPackageTree) => {
+  const dirs = [];
+  if (!env.LOCALAPPDATA) return dirs;
+  const winget = paths.join(env.LOCALAPPDATA, 'Microsoft', 'WinGet');
+  dirs.push(paths.join(winget, 'Links'), ...wingetPackageDirs(filesystem, paths, paths.join(winget, 'Packages'), wingetPackageTree));
+  return dirs;
+};
+
 /** 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 names = sopsNames(env, win, pathext);
   const dirs = String(env.PATH ?? '').split(win ? ';' : ':').filter(Boolean);
-  if (win && env.LOCALAPPDATA) {
-    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 */ }
-  }
+  if (win) dirs.push(...wingetDirs(filesystem, paths, env, wingetPackageTree));
   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 */ }
@@ -83,7 +100,7 @@ export function runSopsFile(bin, args, operation, options = {}) {
 }
 
 const SELECTED_SOPS_VERSIONS = new Set(['3.13.2', '3.13.3']);
-const SELECTED_AGE_VERSIONS = new Set(['1.2.1', '1.3.1']);
+export 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']);
 
@@ -119,7 +136,7 @@ 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 captured = 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') {
@@ -141,115 +158,176 @@ const ownedRequest = request => {
   return { inputType: flags['--input-type'], outputType: flags['--output-type'], file: args.at(-1), recipient: flags['--age'] };
 };
 
+/** The admitted identity key, or the unchanged refusal/failure result (admitted.key is absent then). */
+const selectedAdmission = (selection, spec, invocation, env) => {
+  const fail = () => ({ status: null, stdout: '', stderr: '', error: selection.error });
+  if (!spec || !['binary', 'json', 'yaml', 'dotenv'].includes(spec.inputType) || !['binary', 'json', 'yaml', 'dotenv'].includes(spec.outputType)) return fail();
+  if (!invocation || typeof invocation.runProgram !== 'function' || typeof invocation.resolveRealTool !== 'function') return fail();
+  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 fail();
+  return { key };
+};
+
+const decryptArgs = (file, inputType, outputType) => ['decrypt', '--input-type', inputType, '--output-type', outputType, '--filename-override', file, '--enable-local-keyservice=true', '--decryption-order', 'age'];
+
+const decryptSelected = (run, exe, file, input, spec, recipient) => {
+  const envelope = selectedAgeEnvelope(decoded(input), spec.inputType, recipient);
+  if (!envelope.ok) return held(envelope.reason);
+  const result = run(exe, decryptArgs(file, spec.inputType, spec.outputType), input);
+  if (!captured(result)) return held('selected-decryption-failed');
+  return { status: 0, stdout: decoded(result.stdout), stderr: '', error: null };
+};
+
+const encryptSelected = (run, exe, file, input, spec, recipient) => {
+  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(file, spec.outputType, spec.inputType), result.stdout);
+  if (!captured(readback)) return held('selected-readback-failed');
+  return { status: 0, stdout: text, stderr: '', error: null };
+};
+
+const wipeCaptures = (captures) => {
+  for (const result of captures) {
+    if (Buffer.isBuffer(result?.stdout)) result.stdout.fill(0);
+    if (Buffer.isBuffer(result?.stderr)) result.stderr.fill(0);
+  }
+};
+
+// The one recipient an `age -y` capture names, or null.
+const recipientOf = (stdout) => {
+  const recipients = decoded(stdout).trim().split(/\r?\n/);
+  return recipients.length === 1 && /^age1[ac-hj-np-z02-9]+$/.test(recipients[0]) ? recipients[0] : null;
+};
+
+const toolProfileSupported = (version, ageVersion) => captured(version) && captured(ageVersion)
+  && SELECTED_SOPS_VERSIONS.has(/^sops\s+(\d+\.\d+\.\d+)/.exec(decoded(version.stdout))?.[1])
+  && SELECTED_AGE_VERSIONS.has(/^v?(\d+\.\d+\.\d+)/.exec(decoded(ageVersion.stdout))?.[1]);
+
+const invalidCaptureBudget = (deadline, maxBuffer) => !Number.isInteger(deadline) || deadline < 1 || deadline > 2_147_483_647 || !Number.isInteger(maxBuffer) || maxBuffer < 1;
+
+// The document bytes into `state.input`; the refusal when they are unavailable or over budget, else null.
+const readSelectedInput = (state, request, spec, file) => {
+  try { state.input = request.operation === 'seal' ? Buffer.from(spec.plaintext) : readSecretBytes(file); } catch { return held('actual-document-unavailable'); }
+  return state.input.length > CREDENTIAL_FILE_MAX_BYTES ? held('document-over-budget') : null;
+};
+
+const selectedRunner = (invocation, options, captures, selectedEnv) => (program, args, bytes, childEnv = selectedEnv) => {
+  const result = invocation.runProgram(program, args, { ...options, env: childEnv, input: bytes });
+  captures.push(result); return result;
+};
+
+const performSelected = (state, { bin, request, spec, key, selection, invocation, env, cwd, maxBuffer, timeout }) => {
+  const file = path.resolve(cwd ?? process.cwd(), spec.file);
+  const unavailable = readSelectedInput(state, request, spec, file);
+  if (unavailable) return unavailable;
+  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 (invalidCaptureBudget(deadline, maxBuffer)) return held('invalid-capture-budget');
+  state.selectedEnv = isolatedSopsEnv(env, selection.inlineName);
+  const publicEnv = isolatedSopsEnv(env, null);
+  const options = { cwd, env: state.selectedEnv, shell: false, encoding: 'buffer', windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'], timeout: deadline, maxBuffer };
+  const run = selectedRunner(invocation, options, state.captures, state.selectedEnv);
+  const version = run(exe, ['--disable-version-check', '--version'], undefined, publicEnv);
+  const ageVersion = run(age, ['--version'], undefined, publicEnv);
+  if (!toolProfileSupported(version, ageVersion)) return held('unsupported-tool-profile');
+  state.identity = Buffer.from(key.trim(), 'utf8');
+  const derived = run(age, ['-y'], state.identity, publicEnv);
+  if (!captured(derived)) return held('recipient-unproven');
+  const recipient = recipientOf(derived.stdout);
+  if (recipient === null) return held('recipient-unproven');
+  if (request.operation === 'decrypt') return decryptSelected(run, exe, file, state.input, spec, recipient);
+  return encryptSelected(run, exe, file, state.input, spec, recipient);
+};
+
 /** 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 = [];
+  const admitted = selectedAdmission(selection, spec, invocation, env);
+  if (!admitted.key) return admitted;
+  const state = { input: undefined, identity: undefined, selectedEnv: undefined, 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 };
+    return performSelected(state, { bin, request, spec, key: admitted.key, selection, invocation, env, cwd, maxBuffer, timeout });
   } 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;
+    state.identity?.fill(0); state.input?.fill(0);
+    wipeCaptures(state.captures);
+    if (state.selectedEnv) delete state.selectedEnv.SOPS_AGE_KEY;
   }
 }
 
+const identityRequestValid = ({ env, cwd, invocation, assertLease, consume }) =>
+  env && typeof env === 'object' && path.isAbsolute(cwd ?? '') && typeof consume === 'function'
+    && typeof assertLease === 'function' && typeof invocation?.runProgram === 'function'
+    && typeof invocation?.resolveRealTool === 'function';
+const identityLinesValid = (lines, identities) => identities.length === 1 && /^AGE-SECRET-KEY-1[0-9A-Z]+$/.test(identities[0])
+  && !lines.some(line => line.startsWith('#') && !/^# (?:created:|public key:)/.test(line));
+const declaredRecipientMatches = (lines, recipient) => {
+  const declared = lines.filter(line => line.startsWith('# public key:'));
+  return declared.length === 1 && declared[0].slice('# public key:'.length).trim() === recipient;
+};
+const publicationShaped = (publication) => publication && typeof publication.ok === 'boolean' && ['none', 'unknown', 'complete'].includes(publication.effectState);
+const publicationDurable = (publication) => [true, false].includes(publication.created) && ['file-fsync', 'file-and-parent-fsync', 'file-fsync-namespace-unqualified'].includes(publication.durability);
+
+const identityFailure = (reason, generated) => ({ ok: false, reason, captureState: generated ? 'unknown' : 'none', effectState: generated ? 'unknown' : 'none' });
+
+// The outcome of handing the captured identity to the installer's publication.
+const publicationOutcome = (publication, recipient) => {
+  if (!publicationShaped(publication)) return identityFailure('publication-unknown', true);
+  if (!publication.ok || publication.effectState !== 'complete') return { ok: false, captureState: 'generated', effectState: publication.effectState,
+    reason: 'publication-held' };
+  if (!publicationDurable(publication)) return identityFailure('publication-unknown', true);
+  return { ok: true, captureState: 'generated', effectState: 'complete', created: publication.created,
+    durability: publication.durability, publicRecipient: recipient };
+};
+
+// One age-keygen run under the caller's lease, its capture kept for wiping.
+const leasedAgeRunner = (invocation, age, options, captures, assertLease) => (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 generateAndPublish = (state, { env, cwd, invocation, assertLease, consume }) => {
+  const age = invocation.resolveRealTool('age-keygen', { env });
+  if (!nativeFile(age)) return identityFailure('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 = leasedAgeRunner(invocation, age, options, state.captures, assertLease);
+  const version = run(['--version']);
+  if (!SELECTED_AGE_VERSIONS.has(/^v?(\d+\.\d+\.\d+)/.exec(decoded(version.stdout))?.[1])) return identityFailure('unsupported-tool-profile', false);
+  if (assertLease() !== true) return identityFailure('lease-lost', false);
+  state.generated = true;
+  const made = run([]), lines = decoded(made.stdout).trim().split(/\r?\n/);
+  const identities = lines.filter(line => line && !line.startsWith('#'));
+  if (!identityLinesValid(lines, identities)) return identityFailure('capture-incomplete', true);
+  state.identity = Buffer.from(identities[0], 'utf8');
+  const recipient = recipientOf(run(['-y'], state.identity).stdout);
+  if (recipient === null) return identityFailure('recipient-unproven', true);
+  if (!declaredRecipientMatches(lines, recipient) || assertLease() !== true) return identityFailure('recipient-unproven', true);
+  return publicationOutcome(consume(state.identity, recipient), recipient);
+};
+
 /** 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;
+  if (!identityRequestValid({ env, cwd, invocation, assertLease, consume })) return identityFailure('invalid-request', false);
+  const state = { captures: [], generated: false, identity: undefined };
   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); }
+    return generateAndPublish(state, { env, cwd, invocation, assertLease, consume });
+  } catch { return identityFailure('capture-or-publication-unknown', state.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);
-    }
+    state.identity?.fill(0);
+    wipeCaptures(state.captures);
   }
 }

package/runtime/scripts/hfs/allows.mjs

@@ -36,9 +36,9 @@ export function slotAdmitsFile(resolver, file) {
   if (classified.status === 'no-slot' || classified.status === 'ambiguous' || !classified.slot) return null;
   const slot = resolver.slot(classified.slot);
   const relative = relativeToRoot(classified.path, classified.root);
-  const hit = matchersOf([...(slot.requires ?? []), ...(slot.allows ?? [])], classified.bindings).find(matcher => matcher.expression.test(relative));
-  const forbidden = matchersOf(slot.forbids, classified.bindings).find(matcher => matcher.expression.test(relative) || matcher.expression.test(`${relative}/`));
-  return Boolean(hit) && !forbidden;
+  const hit = matchersOf([...(slot.requires ?? []), ...(slot.allows ?? [])], classified.bindings).some(matcher => matcher.expression.test(relative));
+  const forbidden = matchersOf(slot.forbids, classified.bindings).some(matcher => matcher.expression.test(relative) || matcher.expression.test(`${relative}/`));
+  return hit && !forbidden;
 }
 
 /**