@homeflare/alchemy 0.6.0 → 0.8.0

package/src/cloudflare/mesh-node.ts

@@ -0,0 +1,120 @@
+/**
+ * `Cloudflare.MeshNode` — a Cloudflare Mesh node (a `warp_connector` object), declared without
+ * its token ever touching Alchemy state. Usage and the enrolment step: docs/mesh-node.md.
+ *
+ * 🔴 WHY THIS EXISTS ALONGSIDE `Cloudflare.Tunnel.WarpConnector`. A Mesh node that fronts a
+ *   private service needs a node record in the graph, so the Gateway rules and DNS records that
+ *   name it deploy together. Alchemy beta.79's WarpConnector would put the node token — the
+ *   credential that lets any Linux host join the account's Mesh as that node — into plaintext
+ *   state on every read, and it cannot create an HA node. See mesh-node-form.ts.
+ *
+ * ★ REMOVAL POLICY: `retain` BY DEFAULT — see the ★ on `MeshNode` below, and what it does to an
+ *   `ha` replace in mesh-node-lifecycle.ts.
+ */
+import { Credentials } from '@distilled.cloud/cloudflare/Credentials';
+import * as Cloudflare from 'alchemy/Cloudflare';
+import { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import { Resource, type ResourceClass } from 'alchemy/Resource';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import {
+  type MeshNodeAttributes,
+  type MeshNodeProps,
+  diffMeshNode,
+  validateMeshNode,
+} from './mesh-node-form.ts';
+import { deleteMeshNode, readMeshNode, reconcileMeshNode } from './mesh-node-lifecycle.ts';
+import type { Providers } from './providers.ts';
+
+export interface MeshNode extends Resource<
+  'Cloudflare.MeshNode',
+  MeshNodeProps,
+  MeshNodeAttributes,
+  never,
+  Providers
+> {}
+
+/**
+ * ★ `defaultRemovalPolicy: 'retain'`, LIKE EVERY KIT RESOURCE WHOSE DELETION BREAKS ITS CONSUMERS
+ *   (the `Bao.*` families, `R2BucketLock`, the Proxmox storage families; the reasoning is written
+ *   once in proxmox/resource.ts). Deleting a node cuts every enrolled replica off the Mesh, and
+ *   nothing brings it back: a new node has a new id, a new token and a new Mesh IP per replica, so
+ *   each host must be re-enrolled by hand and every Gateway rule or allow-list that pins the old
+ *   Mesh IP breaks. So dropping the declaration, or `alchemy destroy`, leaves the node live.
+ * ⚠️ IT ALSO SKIPS THE OLD NODE'S DELETE IN A REPLACE (Apply.ts, `deleteOldGenerations` and the
+ *   GC's `retainOldGeneration`, beta.79). A same-name `ha` change therefore REFUSES, deleting
+ *   nothing, until that deploy opts in with `.pipe(RemovalPolicy.destroy())`; a create-first
+ *   replace leaves the old node live and unmanaged. Both measured in mesh-node-policy.test.ts.
+ * ⛔ `delete` STAYS FULLY IMPLEMENTED. Retain is Terraform's `prevent_destroy`, not a stub: it runs
+ *   the moment a declaration opts in with `.pipe(RemovalPolicy.destroy())`.
+ */
+export const MeshNode: ResourceClass<MeshNode> = Resource<MeshNode>('Cloudflare.MeshNode', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** What every call below needs: the account, credentials and HTTP — Alchemy's own trio. */
+export type MeshNodeServices =
+  | Cloudflare.CloudflareEnvironment
+  | Credentials
+  | HttpClient.HttpClient;
+
+/** The account id, resolved the way every `alchemy/Cloudflare` provider resolves it. */
+const accountId = Effect.gen(function* () {
+  const resolved = yield* yield* Cloudflare.CloudflareEnvironment;
+  return resolved.accountId;
+});
+
+/**
+ * ★ `Provider.effect`, CAPTURING THE THREE SERVICES AT BUILD. `Provider.succeed` (what Alchemy's
+ *   own providers use) leaves each handler to find CloudflareEnvironment and Credentials in the
+ *   engine's context at call time — which works for `Cloudflare.providers()` only because it
+ *   `provideMerge`s them into the stack. Capturing them here keeps this provider correct whether
+ *   or not the stack also merges `Cloudflare.providers()`.
+ */
+export const MeshNodeProvider = () =>
+  Provider.effect(
+    MeshNode,
+    Effect.gen(function* () {
+      const services = Context.make(
+        Cloudflare.CloudflareEnvironment,
+        yield* Cloudflare.CloudflareEnvironment,
+      ).pipe(
+        Context.add(Credentials, yield* Credentials),
+        Context.add(HttpClient.HttpClient, yield* HttpClient.HttpClient),
+      );
+      const run = <A, E>(effect: Effect.Effect<A, E, MeshNodeServices>) =>
+        Effect.provideContext(effect, services);
+
+      return MeshNode.Provider.of({
+        stables: ['id', 'accountId', 'ha'],
+        /**
+         * ⛔ EMPTY, AND `nuke.skip`. Alchemy's own `Cloudflare.Tunnel.WarpConnector` already lists
+         *   every `warp_connector` in the account for `alchemy unsafe nuke`; a second listing here
+         *   would make nuke delete each node twice. `read` does not depend on this.
+         */
+        list: () => Effect.succeed([]),
+        nuke: { skip: true },
+        /**
+         * ⛔ VALIDATE AT PLAN TIME, NOT ONLY IN `reconcile`. An `ha` replace is delete-first: the
+         *   engine deletes the old node BEFORE the new generation's reconcile runs, so a
+         *   declaration refused there would leave no node at all. launchd's job-preflight.ts
+         *   refuses at plan time for the same reason.
+         */
+        diff: ({ news, output }) =>
+          run(
+            Effect.gen(function* () {
+              const invalid = isResolved(news) ? validateMeshNode(news) : undefined;
+              if (invalid !== undefined) return yield* Effect.fail(invalid);
+              return diffMeshNode(news, output, yield* accountId);
+            }),
+          ),
+        read: ({ olds, output }) =>
+          run(Effect.flatMap(accountId, (account) => readMeshNode(account, olds, output))),
+        reconcile: ({ news, output }) =>
+          run(Effect.flatMap(accountId, (account) => reconcileMeshNode(account, news, output))),
+        delete: ({ output }) => run(deleteMeshNode(output)),
+      });
+    }),
+  );

package/src/cloudflare/providers.ts

@@ -8,16 +8,34 @@
  *   both a `Cloudflare.R2.Bucket` and this lock merges the two:
  *   `Layer.mergeAll(Cloudflare.providers(), HomeflareCloudflare.providers())` — the shape
  *   a consuming stack names for one talking to more than one account.
+ *
+ * ★ TWO CREDENTIAL PATHS, ONE PER SDK. `R2BucketLock` uses the `cloudflare` SDK through
+ *   `CloudflareApiLive` (`CLOUDFLARE_API_TOKEN`, fail-closed). `MeshNode` uses Alchemy's own SDK
+ *   and resolves credentials and the account through `Cloudflare.CloudflareApiLive()` — the same
+ *   source `Cloudflare.providers()` uses (an Alchemy profile, or `CLOUDFLARE_API_TOKEN` +
+ *   `CLOUDFLARE_ACCOUNT_ID` in CI), so a node lands in the account its Gateway rules do.
+ * ⚠️ That second layer is built again here even when the stack also merges
+ *   `Cloudflare.providers()`. `Layer.provide`, not `provideMerge`: it feeds MeshNode only and adds
+ *   nothing to the stack's context.
  */
+import * as Cloudflare from 'alchemy/Cloudflare';
 import * as Provider from 'alchemy/Provider';
 import * as Layer from 'effect/Layer';
 import { CloudflareApiLive } from './client.ts';
+import { MeshNode, MeshNodeProvider } from './mesh-node.ts';
 import { R2BucketLock, R2BucketLockProvider } from './r2-bucket-lock.ts';
 
 export class Providers extends Provider.ProviderCollection<Providers>()('HomeflareCloudflare') {}
 
 export const providers = () =>
-  Layer.effect(Providers, Provider.collection([R2BucketLock])).pipe(
-    Layer.provide(R2BucketLockProvider()),
+  Layer.effect(Providers, Provider.collection([R2BucketLock, MeshNode])).pipe(
+    Layer.provide(
+      Layer.mergeAll(
+        R2BucketLockProvider(),
+        // ⛔ `orDie`, as `Cloudflare.providers()` ends with: a stack's providers layer must not
+        //   fail, and a profile that cannot resolve is a defect carrying Alchemy's own sentence.
+        MeshNodeProvider().pipe(Layer.provide(Cloudflare.CloudflareApiLive()), Layer.orDie),
+      ),
+    ),
     Layer.provideMerge(CloudflareApiLive),
   );

package/src/index.ts

@@ -10,6 +10,7 @@
  *     import { TalosCluster } from '@homeflare/alchemy/talos';
  *     import { ProxmoxAcl } from '@homeflare/alchemy/proxmox';
  *     import { LaunchdJob } from '@homeflare/alchemy/launchd';
+ *     import { CaddyConfig } from '@homeflare/alchemy/caddy';
  *
  * ★ WHY THESE EXIST AT ALL. When Alchemy has no resource for something, the alternative
  *   is a runbook step a human runs once — and a plan can never show a missing runbook

package/src/launchd/fake-sudo.ts

@@ -0,0 +1,136 @@
+/**
+ * A sudo runner over fake-runner.ts, for the tests beside it: the deploying user is uid 501 and
+ * unprivileged, and `/usr/bin/sudo` is a tiny interpreter that runs the three allowlisted programs
+ * against the same in-memory host, as root.
+ *
+ * ⛔ TEST-ONLY, like fake-runner.ts: no provider imports it, it is not on the barrel, and it never
+ *   runs a real program. No test anywhere runs a real sudo.
+ * ★ THE INTERPRETER READS ONLY WHAT THE ARGV SAYS — mode, owner, group, source, destination — so a
+ *   runner that dropped `-o` or wrote the wrong path shows up as the wrong file, not a passing test.
+ * ★ THE BASE STAYS UNPRIVILEGED, so a write under /Library/LaunchDaemons that skipped sudo fails
+ *   with the fake's EACCES instead of quietly succeeding.
+ * ★ SUDO REFUSES A CALL THAT WAS NOT LOGGED FIRST, so every test holds the runner to "logged
+ *   before it runs", not merely "logged at some point".
+ */
+import { fakeRunner } from './fake-runner.ts';
+import { LAUNCHCTL } from './launchctl.ts';
+import type { ExecResult, HostRunner } from './runner.ts';
+import { INSTALL, RM, SUDO } from './sudo-allowlist.ts';
+import { makeSudoRunner } from './sudo-runner.ts';
+
+export const OPERATOR = 501;
+export const PREFIXES = ['/Library/LaunchDaemons', '/opt/example'];
+
+const ok: ExecResult = { exitCode: 0, stderr: '', stdout: '' };
+
+/** What `sudo -n` prints (exit 1) when it will not run the command. Reasoned; see sudo-runner.ts. */
+export const SUDO_SAYS = {
+  denied:
+    "Sorry, user someone is not allowed to execute '/bin/launchctl bootout system/x' as root on example.\n",
+  'not-in-sudoers': 'someone is not in the sudoers file.\n',
+  'not-on-host': 'someone is not allowed to run sudo on example.\n',
+  password: 'sudo: a password is required\n',
+} as const;
+const fail = (exitCode: number, stderr: string): ExecResult => ({ exitCode, stderr, stdout: '' });
+
+/** Parse `install -S -m MODE [-o UID] [-g GID] SRC DEST` the way install(1) would. */
+const parseInstall = (args: readonly string[]) => {
+  const mode = Number.parseInt(args[2] ?? '', 8);
+  const rest = args.slice(3);
+  const flag = (name: string) => {
+    const at = rest.indexOf(name);
+    return at === -1 ? undefined : Number(rest[at + 1]);
+  };
+  return {
+    dest: rest[rest.length - 1] ?? '',
+    gid: flag('-g'),
+    mode,
+    source: rest[rest.length - 2] ?? '',
+    uid: flag('-o'),
+  };
+};
+
+/** `groups` is the operator's `id -G`; `'unknown'` models that lookup failing. */
+export const fakeSudoHost = (
+  groups: readonly number[] | 'unknown' = [20, 80],
+  prefixes: readonly string[] = PREFIXES,
+) => {
+  const fake = fakeRunner({
+    dirs: {
+      '/Library/LaunchDaemons': 0,
+      '/opt/example': 0,
+      '/opt/example/app': 0,
+      '/Users/someone/Library/LaunchAgents': OPERATOR,
+      '/Users/other/Library/LaunchAgents': 502,
+      // Root-owned, and deliberately NOT a prefix: the forgotten-prefix case.
+      '/etc/example': 0,
+    },
+    euid: OPERATOR,
+    users: {
+      other: { gid: 20, home: '/Users/other', uid: 502 },
+      someone: { gid: 20, home: '/Users/someone', uid: OPERATOR },
+    },
+  });
+  const staged = new Map<string, Uint8Array>();
+  const logs: string[] = [];
+  const sudoCalls: string[][] = [];
+  const state = {
+    /** What sudo itself answers: runs the command, or refuses it with one of SUDO_SAYS. */
+    sudo: 'ok' as 'ok' | keyof typeof SUDO_SAYS,
+    /** Returned by `install` in place of success; nothing is written. */
+    installFailure: undefined as ExecResult | undefined,
+    stagedCount: 0,
+    /** The staged bytes as `install` saw them, by destination. */
+    installedFrom: new Map<string, string>(),
+  };
+
+  const asRoot = async (argv: readonly string[]): Promise<ExecResult> => {
+    const [program, ...args] = argv;
+    if (program === LAUNCHCTL) return fake.runner.exec(argv);
+    if (program === INSTALL) {
+      if (state.installFailure !== undefined) return state.installFailure;
+      const { dest, gid, mode, source, uid } = parseInstall(args);
+      const bytes = staged.get(source);
+      if (bytes === undefined) return fail(71, `install: ${source}: No such file or directory`);
+      state.installedFrom.set(dest, new TextDecoder().decode(bytes));
+      // ★ No -g: the new file takes its directory's group, as a BSD file create does.
+      const dirGid = (await fake.runner.stat(dest.slice(0, dest.lastIndexOf('/'))))?.gid ?? 0;
+      fake.files.set(dest, { bytes, gid: gid ?? dirGid, kind: 'file', mode, uid: uid ?? 0 });
+      return ok;
+    }
+    if (program === RM) {
+      fake.files.delete(args[2] ?? '');
+      return ok;
+    }
+    return fail(1, `sudo: ${String(program)}: command not found`);
+  };
+
+  const base: HostRunner = {
+    ...fake.runner,
+    exec: async (argv) => {
+      if (argv[0] !== SUDO) return fake.runner.exec(argv);
+      sudoCalls.push([...argv]);
+      if (logs[logs.length - 1] !== `homeflare/launchd sudo -n ${JSON.stringify(argv.slice(3))}`) {
+        throw new Error(`fake sudo: ${JSON.stringify(argv)} was not logged before it ran`);
+      }
+      if (state.sudo !== 'ok') return fail(1, SUDO_SAYS[state.sudo]);
+      // argv is [sudo, -n, --, ...command]
+      return asRoot(argv.slice(3));
+    },
+  };
+
+  const runner = makeSudoRunner(prefixes, {
+    base,
+    groups: async () => (groups === 'unknown' ? undefined : groups),
+    log: (line) => logs.push(line),
+    stage: async (bytes) => {
+      state.stagedCount += 1;
+      const path = `/private/tmp/hf-sudo-${String(state.stagedCount)}/staged`;
+      staged.set(path, bytes);
+      return { dispose: async () => void staged.delete(path), path };
+    },
+  });
+  /** The privileged commands run, without the `sudo -n --` in front. */
+  const privileged = () => sudoCalls.map((call) => call.slice(3));
+  return { fake, logs, privileged, runner, staged, state, sudoCalls };
+};

package/src/launchd/host-effect.ts

@@ -1,13 +1,17 @@
 /**
  * The one place a HostRunner's promises become Effects — plus the one probe of an unresolved
- * `news` both providers' diffs share.
+ * `news` both providers' diffs share, and the engine's adopt setting for a check at apply.
  *
  * ★ The lifecycle files are plain async functions over a HostRunner (see runner.ts for why the
  *   runner is promise-based), so each provider handler is a single `lift(() => step(runner, …))`.
  * ⚠️ A thrown Error stays that Error — its message is the refusal a deploy prints. Anything else
  *   thrown is wrapped, so the failure channel is always an Error with a readable message.
  */
+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';
 
 export const lift = <A>(step: () => Promise<A>): Effect.Effect<A, Error> =>
   Effect.tryPromise({
@@ -26,3 +30,31 @@ export const resolvedString = (news: unknown, key: string): string | undefined =
   const value = (news as Record<string, unknown>)[key];
   return typeof value === 'string' ? value : undefined;
 };
+
+/**
+ * Whether the resource at `fqn` may be adopted, resolved exactly as the planner resolves it (alchemy
+ * beta.79 Plan.ts: `resource.Adopt ?? shouldAdopt`): a resource-scoped `adopt(…)`, else the
+ * `AdoptPolicy` service, else `AlchemyContext.adopt`, else off.
+ * ★ FOR A CREATE THE ENGINE NEVER PROBED. Alchemy skips the adoption probe while `news` holds an
+ *   Output, so an ownership check that must still honour `--adopt` can only run at apply. All three
+ *   reach the apply: Alchemist runs plan AND apply under the session context, which provides the
+ *   services from the CLI flag and the Stack the resources registered on (Alchemist/Session.ts,
+ *   routes/stack.ts; Apply.ts reads the same Stack).
+ * ⛔ THE RESOURCE-SCOPED SETTING WINS, BOTH WAYS. The engine captures `adopt(…)` on the resource at
+ *   registration (Resource.ts `Adopt`, into `Stack.resources[fqn]`) and never hands it to a
+ *   provider. Reading only the deploy-wide flag let `--adopt` take over a resource declared
+ *   `.pipe(adopt(false))` — which the planner refuses — and refused one declared `adopt(true)`.
+ * ⚠️ `resources` carries an `@internal` comment in Alchemy's source, but it is in the published types
+ *   and the planner reads `Adopt` from it. caddy/adopt-scope.test.ts registers through the real
+ *   `Resource`, so an upgrade that stops recording it there fails the suite.
+ */
+export const adoptEnabled = (fqn: string): Effect.Effect<boolean> =>
+  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;
+  });

package/src/launchd/host-file-form.ts

@@ -46,9 +46,12 @@ const identityProblems = (name: string, value: string | number | undefined): str
     : [`${name} ${JSON.stringify(value)} is not a valid user or group name`];
 };
 
-export const fileProblems = (props: HostFileProps): string[] => {
+/**
+ * An absolute, normalised path, or the reasons it is not. ★ Shared with sudo-allowlist.ts, so a
+ *   path the sudo runner may touch as root obeys exactly the rule a declared file does.
+ */
+export const pathProblems = (path: string): string[] => {
   const found: string[] = [];
-  const { path } = props;
   if (!path.startsWith('/')) found.push('path must be absolute');
   // ★ One spelling per file: `a/./b`, `a//b` and `a/../b` would each be a second resource for the
   //   same inode, and `..` is how a derived path walks out of the directory it was meant for.
@@ -62,6 +65,11 @@ export const fileProblems = (props: HostFileProps): string[] => {
     found.push('path must be normalised (no trailing slash, no empty, "." or ".." segments)');
   }
   if (path.includes('\x00')) found.push('path contains NUL');
+  return found;
+};
+
+export const fileProblems = (props: HostFileProps): string[] => {
+  const found = pathProblems(props.path);
   const mode = props.mode ?? DEFAULT_MODE;
   if (!Number.isSafeInteger(mode) || mode < 0 || mode > 0o7777) found.push('mode must be 0–0o7777');
   found.push(...identityProblems('owner', props.owner));

package/src/launchd/host-file-lifecycle.ts

@@ -102,7 +102,8 @@ export const reconcileFile = async (
     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.',
+        '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);

package/src/launchd/index.ts

@@ -24,3 +24,5 @@ export { PlistError, renderPlist } from './plist.ts';
 export { launchdProviders } from './providers.ts';
 export type { ExecResult, FileStat, HostRunner, HostUser, WriteOptions } from './runner.ts';
 export { HostRunnerService, canActAsRoot, hostRunnerLayer } from './runner.ts';
+export type { SudoRunnerOptions } from './sudo-runner.ts';
+export { SudoRefusedError, sudoRunner } from './sudo-runner.ts';

package/src/launchd/job-preflight.ts

@@ -61,8 +61,9 @@ export const assertMayWrite = (runner: HostRunner, label: string, domain: Parsed
   if (domain.kind === 'system') {
     throw refuse(
       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.',
+      '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()) {

package/src/launchd/job-validate.ts

@@ -15,7 +15,7 @@ import {
 import { jobSecretProblems } from './secret-tripwire.ts';
 
 /** ★ Labels become file names: no `/`, no leading dot, nothing a path could re-interpret. */
-const LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
+export const LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
 
 /**
  * ⛔ LABELS OTHER TOOLS OWN ARE NEVER DECLARED HERE. nix-darwin (`org.nixos.*`) rewrites its plists

package/src/launchd/local-runner.ts

@@ -5,7 +5,8 @@
  *   the published dist also loads under node (the package's smoke test and the kit's AGENTS.md:
  *   consumers run dist/, not src/), and both runtimes implement these modules.
  * ⛔ NO ELEVATION, EVER. `privileged` is false; a system-domain write succeeds only when the whole
- *   deploy was started as root. See the ⛔ on HostRunner.privileged for why nothing here calls sudo.
+ *   deploy was started as root. See the ⛔ on HostRunner.privileged for why nothing here calls sudo;
+ *   the opt-in elevating runner is sudo-runner.ts, which wraps this one.
  * ⛔ NO SHELL. `exec` spawns argv directly, so a label, path or argument can never be re-parsed
  *   as shell syntax.
  */
@@ -21,13 +22,15 @@ export type LocalRunnerOptions = {
   readonly execTimeoutMs?: number;
 };
 
-const code = (cause: unknown): string | undefined =>
+/** The errno code of a thrown fs error (`ENOENT`, `EACCES`, …), if it has one. */
+export const errnoCode = (cause: unknown): string | undefined =>
   typeof cause === 'object' && cause !== null && 'code' in cause
     ? String((cause as { code: unknown }).code)
     : undefined;
 
 /** ENOENT and ENOTDIR both mean "nothing is at this path". */
-const absent = (cause: unknown): boolean => code(cause) === 'ENOENT' || code(cause) === 'ENOTDIR';
+const absent = (cause: unknown): boolean =>
+  errnoCode(cause) === 'ENOENT' || errnoCode(cause) === 'ENOTDIR';
 
 const run = (argv: readonly string[], timeoutMs: number): Promise<ExecResult> =>
   new Promise((resolve, reject) => {

package/src/launchd/providers.test.ts

@@ -212,11 +212,14 @@ describe('the barrel', () => {
       'LaunchdJob',
       'LaunchdJobProvider',
       'PlistError',
+      'SudoRefusedError',
       'canActAsRoot',
       'hostRunnerLayer',
       'launchdProviders',
       'localRunner',
       'renderPlist',
+      // ★ The opt-in elevating runner; makeSudoRunner and the allowlist internals stay off.
+      'sudoRunner',
     ]);
   });
 });

package/src/launchd/providers.ts

@@ -7,7 +7,8 @@
  *   written by the same identity on the same host — a stack cannot write the file as one user and
  *   bootstrap the job as another by accident.
  * ⚠️ The default is localRunner(): this process, never elevated. A system-domain job therefore
- *   needs the deploy itself started as root, or a runner passed here with `privileged: true`.
+ *   needs the deploy itself started as root, or a runner passed here with `privileged: true` —
+ *   `launchdProviders(sudoRunner({ prefixes }))` is the kit's own (sudo-runner.ts).
  */
 import * as Layer from 'effect/Layer';
 import { HostFileProvider } from './host-file.ts';

package/src/launchd/runner.ts

@@ -48,13 +48,15 @@ export type HostUser = { readonly uid: number; readonly gid: number; readonly ho
 
 export interface HostRunner {
   /**
-   * ⛔ DECLARED, NEVER INFERRED. `true` only when every call this runner makes already runs with
-   *   root's authority — a runner that talks to a root helper, say. The providers refuse
+   * ⛔ DECLARED, NEVER INFERRED. `true` only when this runner can do every root-needing call the
+   *   providers make of it: every call already runs as root (a runner that talks to a root helper,
+   *   say), or the runner elevates exactly those calls (sudoRunner). The providers refuse
    *   system-domain writes unless `effectiveUid()` is 0 or this is `true`, so claiming it falsely
    *   turns that refusal into an EACCES halfway through a deploy.
-   * ⛔ THE KIT NEVER ELEVATES. No runner here calls `sudo`: a deploy that prompts for a password
-   *   mid-plan, or silently uses a cached sudo ticket, is exactly the "no silent sudo" failure. A
-   *   consumer who wants elevation writes that runner deliberately and sets this flag.
+   * ⛔ THE KIT NEVER ELEVATES SILENTLY. localRunner() never calls `sudo`: a deploy that prompts for
+   *   a password mid-plan, or quietly borrows a cached sudo ticket, is exactly the "no silent sudo"
+   *   failure. sudoRunner() does call `sudo -n`, but only when a stack passes it explicitly, only
+   *   for the argv shapes in sudo-allowlist.ts, and logging each one (decided 2026-09-21).
    */
   readonly privileged: boolean;
   /** The uid file writes and launchctl calls run as. */

package/src/launchd/secret-tripwire.ts

@@ -28,7 +28,7 @@ const INLINE_FLAG = /^--?[a-z0-9-]*(?:token|password|passwd|passphrase|secret|ap
 /** A flag whose NEXT argv element is the secret: `--token abc`. */
 const BARE_FLAG = /^--?(?:[a-z0-9]+-)*(?:token|password|passwd|passphrase|secret|api-?key)$/i;
 
-const PRIVATE_KEY = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/;
+export const PRIVATE_KEY = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/;
 
 /** Paths of every string leaf in a plist value holding a private key. */
 const keyLeaves = (value: PlistValue, path: string): string[] => {