@homeflare/alchemy 0.6.0 → 0.8.0

package/dist/launchd/index.js

@@ -6,7 +6,11 @@ import * as Provider from "alchemy/Provider";
 import * as Effect2 from "effect/Effect";
 
 // src/launchd/host-effect.ts
+import { AdoptPolicy } from "alchemy/AdoptPolicy";
+import { AlchemyContext } from "alchemy/AlchemyContext";
+import { Stack } from "alchemy/Stack";
 import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
 var lift = (step) => Effect.tryPromise({
   catch: (cause) => cause instanceof Error ? cause : new Error(String(cause)),
   try: step
@@ -17,6 +21,17 @@ var resolvedString = (news, key) => {
   const value = news[key];
   return typeof value === "string" ? value : undefined;
 };
+var adoptEnabled = (fqn) => Effect.gen(function* () {
+  const stack = yield* Effect.serviceOption(Stack);
+  const scoped = Option.isSome(stack) ? stack.value.resources[fqn]?.Adopt : undefined;
+  if (scoped !== undefined)
+    return scoped;
+  const policy = yield* Effect.serviceOption(AdoptPolicy);
+  if (Option.isSome(policy))
+    return policy.value;
+  const context = yield* Effect.serviceOption(AlchemyContext);
+  return Option.isSome(context) ? context.value.adopt : false;
+});
 
 // src/launchd/secret-tripwire.ts
 var ALTERNATIVE = "props are stored unencrypted in Alchemy state. Have a secret renderer (e.g. openbao-agent) " + "write it to a root-owned file and declare the file path instead (FOO_FILE=/path, --foo-file /path).";
@@ -69,9 +84,8 @@ var identityProblems = (name, value) => {
   }
   return /^[A-Za-z_][A-Za-z0-9_.-]*$/.test(value) || /^\d+$/.test(value) ? [] : [`${name} ${JSON.stringify(value)} is not a valid user or group name`];
 };
-var fileProblems = (props) => {
+var pathProblems = (path) => {
   const found = [];
-  const { path } = props;
   if (!path.startsWith("/"))
     found.push("path must be absolute");
   if (path.endsWith("/") || path.split("/").slice(1).some((part) => part === "" || part === "." || part === "..")) {
@@ -79,6 +93,10 @@ var fileProblems = (props) => {
   }
   if (path.includes("\x00"))
     found.push("path contains NUL");
+  return found;
+};
+var fileProblems = (props) => {
+  const found = pathProblems(props.path);
   const mode = props.mode ?? DEFAULT_MODE;
   if (!Number.isSafeInteger(mode) || mode < 0 || mode > 4095)
     found.push("mode must be 0–0o7777");
@@ -341,7 +359,7 @@ var diffFile = async (runner, news, output) => {
 var reconcileFile = async (runner, props, output) => {
   const want = await desiredFile(runner, props);
   if (want.uid !== undefined && want.uid !== runner.effectiveUid() && !canActAsRoot(runner)) {
-    throw refuse(props.path, `owner ${String(props.owner)} is not the deploying user; only root may chown. Deploy as root ` + "or through a privileged HostRunner (privileged: true). This provider never calls sudo.");
+    throw refuse(props.path, `owner ${String(props.owner)} is not the deploying user; only root may chown. Deploy as root ` + "or through a privileged HostRunner (sudoRunner() with this path under a prefix). This " + "provider never calls sudo itself.");
   }
   const stat = await runner.stat(props.path);
   if (stat !== undefined && stat.kind !== "file") {
@@ -626,7 +644,7 @@ var assertMayWrite = (runner, label, domain) => {
   if (canActAsRoot(runner))
     return;
   if (domain.kind === "system") {
-    throw refuse2(label, "the system domain needs root. Run the deploy as root, or provide a HostRunner that is " + "deliberately privileged (privileged: true). This provider never calls sudo.");
+    throw refuse2(label, "the system domain needs root. Run the deploy as root, or pass a deliberately privileged " + "HostRunner: sudoRunner() elevates exactly the calls this needs. This provider never " + "calls sudo itself.");
   }
   if (domain.uid !== runner.effectiveUid()) {
     throw refuse2(label, `gui/${String(domain.uid)} belongs to another user; only root may write it. ` + "Deploy as that user, as root, or through a privileged HostRunner.");
@@ -835,8 +853,8 @@ var parseGroup = (platform, stdout) => {
 };
 
 // src/launchd/local-runner.ts
-var code = (cause) => typeof cause === "object" && cause !== null && ("code" in cause) ? String(cause.code) : undefined;
-var absent = (cause) => code(cause) === "ENOENT" || code(cause) === "ENOTDIR";
+var errnoCode = (cause) => typeof cause === "object" && cause !== null && ("code" in cause) ? String(cause.code) : undefined;
+var absent = (cause) => errnoCode(cause) === "ENOENT" || errnoCode(cause) === "ENOTDIR";
 var run = (argv, timeoutMs) => new Promise((resolve, reject) => {
   const [program, ...args] = argv;
   if (program === undefined) {
@@ -951,6 +969,320 @@ var localRunner = (options = {}) => {
 // src/launchd/providers.ts
 import * as Layer2 from "effect/Layer";
 var launchdProviders = (runner = localRunner()) => Layer2.mergeAll(LaunchdJobProvider(), HostFileProvider()).pipe(Layer2.provide(hostRunnerLayer(runner)));
+// src/launchd/sudo-allowlist.ts
+class SudoRefusedError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SudoRefusedError";
+  }
+}
+var SUDO = "/usr/bin/sudo";
+var INSTALL = "/usr/bin/install";
+var RM = "/bin/rm";
+var WRITES = new Set(["bootstrap", "bootout", "kickstart"]);
+var octalMode = (mode) => Number.isSafeInteger(mode) && mode >= 0 && mode <= 4095 ? mode.toString(8).padStart(4, "0") : undefined;
+var checkPrefixes = (prefixes) => {
+  if (prefixes.length === 0) {
+    throw new Error("sudoRunner: no prefixes. Name the directories root may write, e.g. /Library/LaunchDaemons.");
+  }
+  for (const prefix of prefixes) {
+    const found = prefix === "/" ? ['"/" would allow every path'] : pathProblems(prefix);
+    if (found.length > 0) {
+      throw new Error(`sudoRunner: prefix ${JSON.stringify(prefix)}: ${found.join("; ")}`);
+    }
+  }
+  return [...prefixes];
+};
+var prefixOf = (path, prefixes) => pathProblems(path).length > 0 ? undefined : prefixes.find((prefix) => path.startsWith(`${prefix}/`));
+var labelOk = (label) => LABEL.test(label) && !RESERVED_LABEL_PREFIXES.some((prefix) => label.startsWith(prefix));
+var systemLabel = (target) => {
+  const label = target?.startsWith("system/") === true ? target.slice("system/".length) : undefined;
+  return label !== undefined && labelOk(label) ? label : undefined;
+};
+var daemonPlist = (label, prefixes) => {
+  const path = plistPathFor(label, { kind: "system" }, undefined);
+  return prefixOf(path, prefixes) === undefined ? undefined : path;
+};
+var NO_DAEMON_PREFIX = "needs /Library/LaunchDaemons among the prefixes, where the job’s plist is written and removed";
+var launchctlProblem = (args, prefixes) => {
+  const [sub, ...rest] = args;
+  if (sub === "bootstrap") {
+    const given = rest[1] ?? "";
+    const name = given.slice(given.lastIndexOf("/") + 1);
+    const label = name.endsWith(".plist") ? name.slice(0, -".plist".length) : "";
+    const shaped = rest.length === 2 && rest[0] === "system" && labelOk(label);
+    if (!shaped)
+      return "bootstrap takes exactly `system /Library/LaunchDaemons/<label>.plist`";
+    const plist = daemonPlist(label, prefixes);
+    if (plist === undefined)
+      return `bootstrap ${NO_DAEMON_PREFIX}`;
+    return given === plist ? undefined : `bootstrap loads only ${plist}, never another path`;
+  }
+  if (sub === "bootout") {
+    const label = rest.length === 1 ? systemLabel(rest[0]) : undefined;
+    if (label === undefined)
+      return "bootout takes exactly `system/<label>`, never a bare domain";
+    return daemonPlist(label, prefixes) === undefined ? `bootout ${NO_DAEMON_PREFIX}` : undefined;
+  }
+  if (sub === "kickstart") {
+    const flags = rest.slice(0, -1);
+    const flagsOk = flags.every((flag) => flag === "-k" || flag === "-p") && new Set(flags).size === flags.length;
+    return flagsOk && systemLabel(rest[rest.length - 1]) !== undefined ? undefined : "kickstart takes only -k / -p, then `system/<label>`";
+  }
+  return `launchctl ${String(sub)} is never run as root`;
+};
+var ID = /^\d+$/;
+var idsOk = (ids) => {
+  const [flag, id, second, secondId] = ids;
+  if (ids.length === 0)
+    return true;
+  if (ids.length === 2)
+    return (flag === "-o" || flag === "-g") && ID.test(id ?? "");
+  return ids.length === 4 && flag === "-o" && ID.test(id ?? "") && second === "-g" && ID.test(secondId ?? "");
+};
+var privilegedProblem = (argv, context) => {
+  const [program, ...args] = argv;
+  const under = (path) => path !== undefined && prefixOf(path, context.prefixes) !== undefined;
+  if (program === LAUNCHCTL)
+    return launchctlProblem(args, context.prefixes);
+  if (program === INSTALL) {
+    const [safe, m, mode, ...rest] = args;
+    if (safe !== "-S" || m !== "-m" || mode === undefined || !/^[0-7]{4}$/.test(mode)) {
+      return "install takes exactly `-S -m <4 octal digits> [-o <uid>] [-g <gid>] <staged> <dest>`";
+    }
+    if (rest.length < 2 || !idsOk(rest.slice(0, -2)))
+      return "install takes only -o <uid> -g <gid>";
+    const [source, dest] = rest.slice(-2);
+    if (source === undefined || source !== context.staged) {
+      return "install copies only the file this runner staged";
+    }
+    return under(dest) ? undefined : "install destination is not under a declared prefix";
+  }
+  if (program === RM) {
+    const [force, end, path, ...extra] = args;
+    return force === "-f" && end === "--" && extra.length === 0 && under(path) ? undefined : "rm takes exactly `-f -- <path under a declared prefix>`";
+  }
+  return `${String(program)} is not on the sudo allowlist`;
+};
+var routeExec = (argv, operatorUid) => {
+  const [program, sub] = argv;
+  if (program === "sudo" || program?.endsWith("/sudo") === true) {
+    return {
+      refuse: "sudoRunner never passes a sudo argv through; it elevates only its allowlist"
+    };
+  }
+  if (program !== LAUNCHCTL || sub === undefined || !WRITES.has(sub))
+    return { as: "operator" };
+  const target = sub === "kickstart" ? argv[argv.length - 1] : argv[2];
+  if (target === "system" || target?.startsWith("system/") === true)
+    return { as: "root" };
+  const owner = /^(?:gui|user)\/(\d+)(?:\/|$)/.exec(target ?? "")?.[1];
+  if (owner === undefined || Number(owner) === operatorUid)
+    return { as: "operator" };
+  return {
+    refuse: `launchctl ${sub} ${String(target)}: that domain belongs to uid ${owner}, and sudoRunner ` + "elevates only the system domain. Deploy as that user, or as root."
+  };
+};
+
+// src/launchd/sudo-guard.ts
+var refuse3 = (path, message) => new SudoRefusedError(`sudoRunner ${path}: ${message}`);
+var betweenDirs = (prefix, path) => {
+  const parts = path.slice(prefix.length + 1).split("/").slice(0, -1);
+  return parts.map((_, index) => `${prefix}/${parts.slice(0, index + 1).join("/")}`);
+};
+var prefixProblem = (stat) => {
+  if (stat === undefined)
+    return "is missing";
+  if (stat.kind !== "directory")
+    return `is a ${stat.kind}, not a directory`;
+  if (stat.uid !== 0)
+    return `is owned by uid ${String(stat.uid)}, not root`;
+  if ((stat.mode & 18) !== 0) {
+    return `is writable by group or other (mode ${stat.mode.toString(8).padStart(4, "0")})`;
+  }
+  return;
+};
+var assertPlainPath = async (base, prefix, path, expect) => {
+  const dirs = betweenDirs(prefix, path);
+  const [prefixStat, ...stats] = await Promise.all([prefix, ...dirs].map((dir) => base.stat(dir)));
+  const bad = prefixProblem(prefixStat);
+  if (bad !== undefined) {
+    throw refuse3(path, `the declared prefix ${prefix} ${bad}. Declare only a real directory that root owns and ` + "only root may write. Nothing ran as root.");
+  }
+  for (const [index, stat] of stats.entries()) {
+    if (stat?.kind !== "directory") {
+      throw refuse3(path, `${String(dirs[index])} is ${stat === undefined ? "missing" : `a ${stat.kind}`}; root ` + "writes only through real directories under a declared prefix.");
+    }
+  }
+  const target = await base.stat(path);
+  if (target === undefined && expect === "file-or-absent")
+    return "absent";
+  if (target?.kind === "file")
+    return "file";
+  throw refuse3(path, `is ${target === undefined ? "missing" : `a ${target.kind}`}, not a file`);
+};
+var canRead = (file, uid, groups) => {
+  if (uid === 0)
+    return true;
+  if (file.uid === uid)
+    return (file.mode & 256) !== 0;
+  const groupRead = (file.mode & 32) !== 0;
+  const otherRead = (file.mode & 4) !== 0;
+  if (groupRead === otherRead)
+    return groupRead;
+  if (groups === undefined)
+    return;
+  return groups.includes(file.gid) ? groupRead : otherRead;
+};
+var assertReadableBack = async (base, path, options, groups) => {
+  const operator = base.effectiveUid();
+  const parent = path.slice(0, path.lastIndexOf("/")) || "/";
+  const gid = options.gid ?? (await base.stat(parent))?.gid ?? 0;
+  const file = { gid, mode: options.mode, uid: options.uid ?? 0 };
+  if (canRead(file, operator, groups) !== false)
+    return;
+  throw refuse3(path, `owner ${String(file.uid)}, group ${String(gid)}, mode ${file.mode.toString(8)} would hide it ` + `from the deploying user (uid ${String(operator)}), who reads every file back. Declare a ` + "mode that user can read, or deploy as root. Nothing was written.");
+};
+var operatorGroups = async (base) => {
+  const result = await base.exec(["/usr/bin/id", "-G"]);
+  const ids = result.stdout.trim().split(/\s+/);
+  return result.exitCode === 0 && ids.every((id) => /^\d+$/.test(id)) ? ids.map(Number) : undefined;
+};
+
+// src/launchd/sudo-stage.ts
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join as join2 } from "node:path";
+var stageFile = async (bytes) => {
+  const dir = await mkdtemp(join2(tmpdir(), "hf-sudo-"));
+  const dispose = () => rm(dir, { force: true, recursive: true });
+  try {
+    const path = join2(dir, "staged");
+    await writeFile(path, bytes, { flag: "wx", mode: 384 });
+    return { dispose, path };
+  } catch (cause) {
+    await dispose();
+    throw cause;
+  }
+};
+
+// src/launchd/sudo-runner.ts
+var PASSWORD = /^sudo: (?:a password is required|a terminal is required|sorry, you must have a tty)/m;
+var NOT_ALLOWED = /^(?:Sorry, user \S+ (?:is not allowed to execute|may not run sudo)|\S+ is not (?:in the sudoers file|allowed to run sudo on ))/m;
+var undeclared = (path, prefixes) => (cause) => {
+  const code = errnoCode(cause);
+  if (code !== "EACCES" && code !== "EPERM")
+    throw cause;
+  throw new Error(`sudoRunner ${path}: ${code} as the deploying user, and the path is under no declared prefix ` + `(${prefixes.join(", ")}). If root owns its directory, declare that directory as a prefix.`, { cause });
+};
+var makeSudoRunner = (prefixList, deps) => {
+  const prefixes = checkPrefixes(prefixList);
+  const { base } = deps;
+  const elevate = async (argv, { before, staged } = {}) => {
+    const shown = JSON.stringify(argv);
+    const problem = privilegedProblem(argv, {
+      prefixes,
+      ...staged === undefined ? {} : { staged }
+    });
+    if (problem !== undefined)
+      throw new SudoRefusedError(`sudoRunner refused ${shown}: ${problem}`);
+    await before?.();
+    deps.log(`homeflare/launchd sudo -n ${shown}`);
+    const result = await base.exec([SUDO, "-n", "--", ...argv]);
+    if (result.exitCode !== 1)
+      return result;
+    if (PASSWORD.test(result.stderr)) {
+      throw new SudoRefusedError(`sudo -n ${shown}: a password is required, and this runner never prompts. Run \`sudo -v\` ` + "in the deploying terminal just before the deploy, or grant exactly these commands " + "NOPASSWD (docs/launchd-sudo.md). The command did not run.");
+    }
+    if (NOT_ALLOWED.test(result.stderr)) {
+      throw new SudoRefusedError(`sudo -n ${shown}: sudoers does not let the deploying user run this. The command did not run.`);
+    }
+    return result;
+  };
+  const mustSucceed = async (argv, staged) => {
+    const result = await elevate(argv, staged === undefined ? {} : { staged });
+    if (result.exitCode !== 0) {
+      const stderr = result.stderr.trim().slice(0, 300);
+      throw new Error(`sudo -n ${JSON.stringify(argv)} -> ${String(result.exitCode)}: ${stderr}`);
+    }
+  };
+  return {
+    effectiveUid: () => base.effectiveUid(),
+    exec: async (argv) => {
+      const route = routeExec(argv, base.effectiveUid());
+      if ("refuse" in route)
+        throw new SudoRefusedError(`sudoRunner: ${route.refuse}`);
+      if (route.as === "operator")
+        return base.exec(argv);
+      const plist = argv[1] === "bootstrap" ? argv[3] : undefined;
+      const prefix = plist === undefined ? undefined : prefixOf(plist, prefixes);
+      return elevate(argv, {
+        before: async () => {
+          if (plist !== undefined && prefix !== undefined) {
+            await assertPlainPath(base, prefix, plist, "file");
+          }
+        }
+      });
+    },
+    lookupGroup: (nameOrId) => base.lookupGroup(nameOrId),
+    lookupUser: (nameOrId) => base.lookupUser(nameOrId),
+    privileged: true,
+    readFile: (path) => base.readFile(path),
+    removeFile: async (path) => {
+      const prefix = prefixOf(path, prefixes);
+      if (prefix === undefined)
+        return base.removeFile(path).catch(undeclared(path, prefixes));
+      if (await base.stat(path) === undefined)
+        return;
+      await assertPlainPath(base, prefix, path, "file");
+      await mustSucceed([RM, "-f", "--", path]);
+    },
+    sleep: (ms) => base.sleep(ms),
+    stat: (path) => base.stat(path),
+    writeFileAtomic: async (path, bytes, options) => {
+      const prefix = prefixOf(path, prefixes);
+      const operator = base.effectiveUid();
+      if (prefix === undefined) {
+        if (options.uid !== undefined && options.uid !== operator && operator !== 0) {
+          throw new SudoRefusedError(`sudoRunner ${path}: owner ${String(options.uid)} needs root, and the path is under no ` + `declared prefix (${prefixes.join(", ")}). Declare its directory, or deploy as root. ` + "Nothing was written.");
+        }
+        return base.writeFileAtomic(path, bytes, options).catch(undeclared(path, prefixes));
+      }
+      const mode = octalMode(options.mode);
+      if (mode === undefined)
+        throw new SudoRefusedError(`sudoRunner ${path}: mode must be 0–0o7777`);
+      await assertPlainPath(base, prefix, path, "file-or-absent");
+      await assertReadableBack(base, path, options, await deps.groups());
+      const staged = await deps.stage(bytes);
+      try {
+        await mustSucceed([
+          INSTALL,
+          "-S",
+          "-m",
+          mode,
+          ...options.uid === undefined ? [] : ["-o", String(options.uid)],
+          ...options.gid === undefined ? [] : ["-g", String(options.gid)],
+          staged.path,
+          path
+        ], staged.path);
+      } finally {
+        await staged.dispose();
+      }
+    }
+  };
+};
+var sudoRunner = (options) => {
+  const base = localRunner(options);
+  return makeSudoRunner(options.prefixes, {
+    base,
+    groups: () => operatorGroups(base),
+    log: options.log ?? ((line) => {
+      process.stderr.write(`${line}
+`);
+    }),
+    stage: stageFile
+  });
+};
 export {
   HostFile,
   HostFileProvider,
@@ -958,12 +1290,14 @@ export {
   LaunchdJob,
   LaunchdJobProvider,
   PlistError,
+  SudoRefusedError,
   canActAsRoot,
   hostRunnerLayer,
   launchdProviders,
   localRunner,
-  renderPlist
+  renderPlist,
+  sudoRunner
 };
 
-//# debugId=86750D103F13F7F764756E2164756E21
+//# debugId=750ACEF7A88B083E64756E2164756E21
 //# sourceMappingURL=index.js.map