@starci/hfs 4.0.9 → 4.1.0

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,312 @@ 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'];
+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 = sopsNames(env, win, pathext);
   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 */ }
+  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 */ }
   }
-  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']);
+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']);
+
+/** 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?.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 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);
+  const admitted = selectedAdmission(selection, spec, invocation, env);
+  if (!admitted.key) return admitted;
+  const state = { input: undefined, identity: undefined, selectedEnv: undefined, captures: [] };
+  try {
+    return performSelected(state, { bin, request, spec, key: admitted.key, selection, invocation, env, cwd, maxBuffer, timeout });
+  } catch { return held('selected-native-refused'); }
+  finally {
+    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 } = {}) {
+  if (!identityRequestValid({ env, cwd, invocation, assertLease, consume })) return identityFailure('invalid-request', false);
+  const state = { captures: [], generated: false, identity: undefined };
+  try {
+    return generateAndPublish(state, { env, cwd, invocation, assertLease, consume });
+  } catch { return identityFailure('capture-or-publication-unknown', state.generated); }
+  finally {
+    state.identity?.fill(0);
+    wipeCaptures(state.captures);
+  }
+}

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

@@ -2,17 +2,21 @@
 // (scripts/hfs/secret.mjs). The plaintext travels on the child's stdin and never on its argument list, so it is not visible in a
 // process listing; the ciphertext comes back on stdout.
 import { spawnSync } from 'node:child_process';
-import { resolveSops } from './lib.mjs';
+import { sopsIdentityEnv } from '../../../engine/secrets.mjs';
+import { resolveSops, runSelectedSops } from './lib.mjs';
 
 /**
  * Run `<bin> encrypt` (bin null: the sops resolveSops finds) over `plaintext` of format `inputType` (json, yaml or dotenv). Sops reads stdin only with a `--filename-override`, the path the sealed
  * file will have: recipients are age keys (`--age`), and when none are given sops picks them from the repository's .sops.yaml for that path. {status, stdout, stderr, error}.
  */
-export function seal(bin, { inputType, plaintext, recipients = [], filenameOverride }, { env = process.env, cwd = undefined, maxBuffer = 16 * 1024 * 1024 } = {}) {
+export function seal(bin, { inputType, plaintext, recipients = [], filenameOverride }, { invocation = null, env = process.env, cwd = undefined, maxBuffer = 16 * 1024 * 1024, timeout = undefined } = {}) {
   const args = ['encrypt', '--input-type', inputType, '--output-type', inputType, '--filename-override', filenameOverride];
   if (recipients.length) args.push('--age', recipients.join(','));
-  const exe = bin ?? resolveSops(env);
+  const selected = sopsIdentityEnv(env);
+  if (selected.error?.identityRefusal === 'inline-context-unqualified') return runSelectedSops(bin, { operation: 'seal', params: { inputType, plaintext, recipients, filenameOverride } }, { 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, { cwd, env, input: plaintext, encoding: 'utf8', windowsHide: true, maxBuffer });
+  const r = spawnSync(exe, args, { cwd, env: selected.env, input: plaintext, encoding: 'utf8', windowsHide: true, maxBuffer });
   return { status: r.status, stdout: r.stdout, stderr: r.stderr, error: r.error ?? null };
 }

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;
 }
 
 /**

package/runtime/scripts/hfs/architecture/ast-walks.mjs

@@ -1,19 +1,20 @@
 // ast-walks.mjs - AST walks the architecture checkers share (moved out of typescript.mjs, which keeps the program loading and module resolution).
 import { canonical, isInside } from './config.mjs';
-import { sourceLocation } from '../../lib/ts-ast.mjs';
+import { hasAnyFlag, isConstVariable, sourceLocation } from '../../lib/ts-ast.mjs';
 import { UNPROVEN_FRAMEWORK, isUnshadowedCommonJsRequire, relativePath, unwrapExpression } from './typescript.mjs';
 
 /** `expression` unwrapped by the caller's own predicate set (a predicate absent on an older ts reads as never). */
 export function unwrapEach(ts, expression, predicates) {
-  while (expression && predicates.some((predicate) => predicate?.(expression))) expression = expression.expression;
-  return expression;
+  let current = expression;
+  while (current && predicates.some((predicate) => predicate?.(current))) current = current.expression;
+  return current;
 }
 
 /** `value` with every TS alias hop resolved (a re-exported import reads as its target symbol). */
-export function normalizedSymbolValue(ts, checker, value) {
-  let symbol = value ?? null;
+export function normalizedSymbolValue(ts, checker, value = null) {
+  let symbol = value;
   const seen = new Set();
-  while (symbol && (symbol.flags & ts.SymbolFlags.Alias) && !seen.has(symbol)) {
+  while (symbol && hasAnyFlag(symbol.flags, ts.SymbolFlags.Alias) && !seen.has(symbol)) {
     seen.add(symbol);
     const target = checker.getAliasedSymbol(symbol);
     if (!target || target === symbol) break;
@@ -48,7 +49,7 @@ export function valueSymbol(ts, checker, node, seen = new Set(), { unselected =
   seen.add(symbol);
   const declarations = symbol.getDeclarations?.() ?? [];
   if (declarations.length === 1 && ts.isVariableDeclaration(declarations[0]) && declarations[0].initializer
-    && (ts.getCombinedNodeFlags(declarations[0].parent) & ts.NodeFlags.Const)) {
+    && isConstVariable(ts, declarations[0])) {
     return valueSymbol(ts, checker, declarations[0].initializer, seen, { unselected });
   }
   return symbol;
@@ -102,50 +103,59 @@ export function anyDescendant(ts, node, match) {
  * selected node's symbols to a kind (default `targets.get(symbol)`); `shorthandOf` (when set) also resolves
  * shorthand-property declarations and descends property assignments; `newExpression` descends `new X()` callees.
  */
+const addKinds = (target, source) => { for (const kind of source) target.add(kind); };
+
+const kindsFromReturns = (ts, checker, declaration, targets, options) => {
+  const kinds = new Set();
+  for (const returned of returnedExpressions(ts, declaration)) addKinds(kinds, tracedFrameworkKinds(ts, checker, returned, targets, options));
+  return kinds;
+};
+
+const kindsFromDeclaration = (ts, checker, declaration, targets, options, shorthandOf) => {
+  const kinds = new Set();
+  if (ts.isVariableDeclaration(declaration) && declaration.initializer)
+    addKinds(kinds, tracedFrameworkKinds(ts, checker, declaration.initializer, targets, options));
+  if (shorthandOf && ts.isShorthandPropertyAssignment(declaration)) {
+    const target = normalizedSymbolValue(ts, checker, checker.getShorthandAssignmentValueSymbol?.(declaration));
+    const kind = shorthandOf(ts, checker, target, targets);
+    if (kind) kinds.add(kind);
+  }
+  if (shorthandOf && ts.isPropertyAssignment(declaration))
+    addKinds(kinds, tracedFrameworkKinds(ts, checker, declaration.initializer, targets, options));
+  addKinds(kinds, kindsFromReturns(ts, checker, declaration, targets, options));
+  return kinds;
+};
+
+const kindsFromSymbol = (ts, checker, symbol, targets, seen, options) => {
+  const nextSeen = new Set(seen).add(symbol);
+  const declarationOptions = { ...options, seen: nextSeen };
+  const kinds = new Set();
+  for (const declaration of symbol.getDeclarations?.() ?? [])
+    addKinds(kinds, kindsFromDeclaration(ts, checker, declaration, targets, declarationOptions, options.shorthandOf));
+  return kinds;
+};
+
+const defaultDirectOf = (ts, checker, { symbol, targets }) => targets.get(symbol) ?? null;
+
 export function tracedFrameworkKinds(ts, checker, expression, targets,
   { seen = new Set(), depth = 0, directOf = null, shorthandOf = null, newExpression = false } = {}) {
   if (!expression) return new Set();
   if (depth > 10) return new Set([UNPROVEN_FRAMEWORK]);
-  expression = unwrapExpression(ts, expression);
-  const selected = selectedNode(ts, expression);
+  const unwrapped = unwrapExpression(ts, expression);
+  const selected = selectedNode(ts, unwrapped);
   const symbol = selected ? normalizedSymbol(ts, checker, selected) : null;
-  const direct = symbol ? (directOf ?? ((ts2, c, { symbol: s, targets: t }) => t.get(s) ?? null))(ts, checker, { symbol, selected, targets }) : null;
+  const direct = symbol ? (directOf ?? defaultDirectOf)(ts, checker, { symbol, selected, targets }) : null;
   if (direct) return new Set([direct]);
-  const opts = { depth: depth + 1, directOf, shorthandOf, newExpression };
-  if (ts.isArrowFunction(expression) || ts.isFunctionExpression(expression)) {
-    const kinds = new Set();
-    for (const returned of returnedExpressions(ts, expression)) {
-      for (const kind of tracedFrameworkKinds(ts, checker, returned, targets, { ...opts, seen })) kinds.add(kind);
-    }
-    return kinds;
-  }
-  if (ts.isCallExpression(expression)) {
-    const kinds = tracedFrameworkKinds(ts, checker, expression.expression, targets, { ...opts, seen });
+  const options = { depth: depth + 1, directOf, shorthandOf, newExpression };
+  if (ts.isArrowFunction(unwrapped) || ts.isFunctionExpression(unwrapped)) return kindsFromReturns(ts, checker, unwrapped, targets, { ...options, seen });
+  if (ts.isCallExpression(unwrapped)) {
+    const kinds = tracedFrameworkKinds(ts, checker, unwrapped.expression, targets, { ...options, seen });
     if (kinds.size) return kinds;
   }
-  if (newExpression && ts.isNewExpression(expression)) {
-    return tracedFrameworkKinds(ts, checker, expression.expression, targets, { ...opts, seen });
-  }
+  if (newExpression && ts.isNewExpression(unwrapped))
+    return tracedFrameworkKinds(ts, checker, unwrapped.expression, targets, { ...options, seen });
   if (!symbol || seen.has(symbol)) return new Set();
-  const nextSeen = new Set(seen).add(symbol);
-  const kinds = new Set();
-  for (const declaration of symbol.getDeclarations?.() ?? []) {
-    if (ts.isVariableDeclaration(declaration) && declaration.initializer) {
-      for (const kind of tracedFrameworkKinds(ts, checker, declaration.initializer, targets, { ...opts, seen: nextSeen })) kinds.add(kind);
-    }
-    if (shorthandOf && ts.isShorthandPropertyAssignment(declaration)) {
-      const target = normalizedSymbolValue(ts, checker, checker.getShorthandAssignmentValueSymbol?.(declaration));
-      const kind = shorthandOf(ts, checker, target, targets);
-      if (kind) kinds.add(kind);
-    }
-    if (shorthandOf && ts.isPropertyAssignment(declaration)) {
-      for (const kind of tracedFrameworkKinds(ts, checker, declaration.initializer, targets, { ...opts, seen: nextSeen })) kinds.add(kind);
-    }
-    for (const returned of returnedExpressions(ts, declaration)) {
-      for (const kind of tracedFrameworkKinds(ts, checker, returned, targets, { ...opts, seen: nextSeen })) kinds.add(kind);
-    }
-  }
-  return kinds;
+  return kindsFromSymbol(ts, checker, symbol, targets, seen, options);
 }
 
 /** 'unproven framework' | 'multiple framework' | the one kind | null, for a decorator whose expression constructs. */
@@ -153,7 +163,8 @@ export function constructedDecoratorKind(ts, checker, decorator, targets, traceO
   const callee = ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression;
   const kinds = tracedFrameworkKinds(ts, checker, callee, targets, traceOpts);
   if (kinds.has(UNPROVEN_FRAMEWORK)) return 'unproven framework';
-  return kinds.size === 1 ? [...kinds][0] : kinds.size ? 'multiple framework' : null;
+  if (kinds.size === 1) return [...kinds][0];
+  return kinds.size ? 'multiple framework' : null;
 }
 
 /** The target a decorator resolves to through a `let`/`var` alias's single initializer, or null. */
@@ -163,7 +174,7 @@ export function mutableDecoratorKind(ts, checker, decorator, targets) {
   const symbol = selected ? normalizedSymbol(ts, checker, selected) : null;
   const declarations = symbol?.getDeclarations?.() ?? [];
   if (declarations.length !== 1 || !ts.isVariableDeclaration(declarations[0]) || !declarations[0].initializer
-    || (ts.getCombinedNodeFlags(declarations[0].parent) & ts.NodeFlags.Const)) return null;
+    || isConstVariable(ts, declarations[0])) return null;
   return targets.get(valueSymbol(ts, checker, declarations[0].initializer)) ?? null;
 }
 
@@ -178,11 +189,12 @@ export function decoratorCallee(ts, decorator) {
  * not resolve. Null when the statement names no static specifier.
  */
 export function moduleExportsOf(ts, checker, statement) {
-  const moduleSpecifier = (ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement))
-    && statement.moduleSpecifier && ts.isStringLiteralLike(statement.moduleSpecifier) ? statement.moduleSpecifier : null;
-  const importEquals = ts.isImportEqualsDeclaration(statement) && ts.isExternalModuleReference(statement.moduleReference)
-    && statement.moduleReference.expression && ts.isStringLiteralLike(statement.moduleReference.expression)
-    ? statement.moduleReference.expression : null;
+  let moduleSpecifier = null;
+  if ((ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement))
+    && statement.moduleSpecifier && ts.isStringLiteralLike(statement.moduleSpecifier)) moduleSpecifier = statement.moduleSpecifier;
+  let importEquals = null;
+  if (ts.isImportEqualsDeclaration(statement) && ts.isExternalModuleReference(statement.moduleReference)
+    && statement.moduleReference.expression && ts.isStringLiteralLike(statement.moduleReference.expression)) importEquals = statement.moduleReference.expression;
   const specifierNode = moduleSpecifier ?? importEquals;
   const specifier = specifierNode?.text;
   if (specifier == null) return null;
@@ -208,7 +220,8 @@ export function programSourcesOf(context, checker, localFiles, { root = null } =
  * The CommonJS require() caveat every framework scan reports: each `require('<specifier>')` `accepted` pushes
  * `${filePath} uses a CommonJS <label ?? specifier> <detail>` (the import-shape reasoning cannot prove that binding).
  */
-export function commonJsRequireReasons(ts, checker, sourceFile, accepted, reasons, filePath, detail, label = null) {
+export function commonJsRequireReasons(ts, checker, sourceFile, accepted, reasons, filePath, detail) {
+  const label = arguments[7] ?? null;
   const visit = node => {
     if (ts.isCallExpression(node) && isUnshadowedCommonJsRequire(ts, checker, node.expression)
       && node.arguments.length === 1 && ts.isStringLiteralLike(node.arguments[0]) && accepted(node.arguments[0].text)) {