@homeflare/alchemy 0.4.1 → 0.6.0

package/src/launchd/providers.test.ts

@@ -0,0 +1,222 @@
+/**
+ * The Alchemy wiring: each provider built as a Layer over a fake HostRunner, its handlers called
+ * the way the engine calls them — plus the barrel, which is the subpath's public API.
+ *
+ * ★ `read` with no prior state is the adoption probe. Anything found must come back `Unowned`, or
+ *   Alchemy would silently take over a job or file some other tool (or a person) put there.
+ */
+import { describe, expect, test } from 'bun:test';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { fakeRunner } from './fake-runner.ts';
+import { HostFile, HostFileProvider } from './host-file.ts';
+import * as barrel from './index.ts';
+import { LaunchdJob, LaunchdJobProvider } from './job.ts';
+import type { LaunchdJobProps } from './job-form.ts';
+import { launchdProviders } from './providers.ts';
+import { hostRunnerLayer } from './runner.ts';
+
+const job: LaunchdJobProps = {
+  domain: 'system',
+  label: 'com.example.job',
+  programArguments: ['/usr/local/bin/job'],
+};
+const ids = { fqn: 'stack/job', id: 'job', instanceId: 'i-1' };
+
+/** A handler the provider must define; a missing one fails the test by name. */
+const handler = <F>(name: string, fn: F | undefined): F => {
+  if (fn === undefined) throw new Error(`provider has no ${name} handler`);
+  return fn;
+};
+
+const host = () =>
+  fakeRunner({ dirs: { '/Library/LaunchDaemons': 0, '/etc/example': 0 }, euid: 0 });
+
+const withJobProvider = <A>(
+  fake: ReturnType<typeof host>,
+  use: (p: Effect.Success<typeof LaunchdJob.Provider>) => Effect.Effect<A, Error>,
+) =>
+  Effect.runPromise(
+    Effect.gen(function* () {
+      return yield* use(yield* LaunchdJob.Provider);
+    }).pipe(Effect.provide(LaunchdJobProvider().pipe(Layer.provide(hostRunnerLayer(fake.runner))))),
+  );
+
+describe('LaunchdJobProvider', () => {
+  test('reconcile, then read with state (owned) and without (Unowned)', async () => {
+    const fake = host();
+    const [owned, probe] = await withJobProvider(fake, (provider) =>
+      Effect.gen(function* () {
+        const session = undefined as never;
+        const output = yield* provider.reconcile({
+          ...ids,
+          bindings: [] as never,
+          news: job,
+          olds: undefined,
+          output: undefined,
+          session,
+        });
+        const owned = yield* handler('read', provider.read)({ ...ids, olds: job, output });
+        const probe = yield* handler(
+          'read',
+          provider.read,
+        )({ ...ids, olds: job, output: undefined });
+        return [owned, probe] as const;
+      }),
+    );
+    expect(Unowned.is(owned)).toBe(false);
+    expect(Unowned.is(probe)).toBe(true);
+    expect(probe).toMatchObject({ label: 'com.example.job', loaded: true });
+  });
+
+  test('diff defers to the engine when there is no prior output', async () => {
+    const diff = await withJobProvider(host(), (provider) =>
+      Effect.map(
+        handler(
+          'diff',
+          provider.diff,
+        )({
+          ...ids,
+          news: job,
+          newBindings: [] as never,
+          oldBindings: [] as never,
+          olds: job,
+          output: undefined,
+        }),
+        (value) => value,
+      ),
+    );
+    expect(diff).toBeUndefined();
+  });
+
+  test('a rename is a replace even while other props are unresolved', async () => {
+    // ★ An Effect is what isResolved() calls unresolved — the stand-in for `config.path` while its
+    //   HostFile is changing in the same deploy. The engine's default here would be `update`.
+    const fake = host();
+    const pending = { ...job, programArguments: [Effect.succeed('/usr/local/bin/job')] } as never;
+    const diffs = await withJobProvider(fake, (provider) =>
+      Effect.gen(function* () {
+        const output = yield* provider.reconcile({
+          ...ids,
+          bindings: [] as never,
+          news: job,
+          olds: undefined,
+          output: undefined,
+          session: undefined as never,
+        });
+        const diff = handler('diff', provider.diff);
+        const base = {
+          ...ids,
+          newBindings: [] as never,
+          oldBindings: [] as never,
+          olds: job,
+          output,
+        };
+        const rename = { ...(pending as object), label: 'com.example.renamed' } as never;
+        return [yield* diff({ ...base, news: rename }), yield* diff({ ...base, news: pending })];
+      }),
+    );
+    expect(diffs).toEqual([{ action: 'replace', deleteFirst: true }, undefined]);
+  });
+
+  test('a refusal reaches Alchemy as a failure carrying its message', async () => {
+    const fake = fakeRunner({ dirs: { '/Library/LaunchDaemons': 0 }, euid: 501 });
+    await expect(
+      withJobProvider(fake, (provider) =>
+        provider.reconcile({
+          ...ids,
+          bindings: [] as never,
+          news: job,
+          olds: undefined,
+          output: undefined,
+          session: undefined as never,
+        }),
+      ),
+    ).rejects.toThrow('never calls sudo');
+  });
+});
+
+describe('HostFileProvider', () => {
+  test('a file already on disk probes as Unowned', async () => {
+    const fake = host();
+    fake.files.set('/etc/example/a.conf', {
+      bytes: new Uint8Array([120]),
+      gid: 0,
+      kind: 'file',
+      mode: 0o644,
+      uid: 0,
+    });
+    const found = await Effect.runPromise(
+      Effect.gen(function* () {
+        const provider = yield* HostFile.Provider;
+        return yield* handler(
+          'read',
+          provider.read,
+        )({ ...ids, olds: { content: 'x', path: '/etc/example/a.conf' }, output: undefined });
+      }).pipe(Effect.provide(HostFileProvider().pipe(Layer.provide(hostRunnerLayer(fake.runner))))),
+    );
+    expect(Unowned.is(found)).toBe(true);
+    expect(found).toMatchObject({ path: '/etc/example/a.conf', size: 1 });
+  });
+
+  test('a new path is a replace even while content is unresolved', async () => {
+    const output = {
+      gid: 0,
+      mode: 0o644,
+      path: '/etc/example/a.conf',
+      sha256: '',
+      size: 1,
+      uid: 0,
+    };
+    const news = { content: Effect.succeed('x'), path: '/etc/example/b.conf' } as never;
+    const diff = await Effect.runPromise(
+      Effect.gen(function* () {
+        const provider = yield* HostFile.Provider;
+        return yield* handler(
+          'diff',
+          provider.diff,
+        )({
+          ...ids,
+          newBindings: [] as never,
+          news,
+          oldBindings: [] as never,
+          olds: { content: 'x', path: output.path },
+          output,
+        });
+      }).pipe(
+        Effect.provide(HostFileProvider().pipe(Layer.provide(hostRunnerLayer(host().runner)))),
+      ),
+    );
+    expect(diff).toEqual({ action: 'replace' });
+  });
+});
+
+describe('launchdProviders', () => {
+  test('provides both providers from one runner', async () => {
+    const both = await Effect.runPromise(
+      Effect.gen(function* () {
+        return [yield* LaunchdJob.Provider, yield* HostFile.Provider];
+      }).pipe(Effect.provide(launchdProviders(host().runner))),
+    );
+    expect(both).toHaveLength(2);
+  });
+});
+
+describe('the barrel', () => {
+  test('exports the public surface and nothing test-only or internal', () => {
+    expect(Object.keys(barrel).sort()).toEqual([
+      'HostFile',
+      'HostFileProvider',
+      'HostRunnerService',
+      'LaunchdJob',
+      'LaunchdJobProvider',
+      'PlistError',
+      'canActAsRoot',
+      'hostRunnerLayer',
+      'launchdProviders',
+      'localRunner',
+      'renderPlist',
+    ]);
+  });
+});

package/src/launchd/providers.ts

@@ -0,0 +1,21 @@
+/**
+ * Both launchd-subpath providers with one HostRunner, as a single layer for a host stack.
+ *
+ *     Layer.mergeAll(launchdProviders(), …the stack's other providers)
+ *
+ * ★ ONE RUNNER FOR BOTH, so a daemon's config file (HostFile) and the daemon (LaunchdJob) are
+ *   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`.
+ */
+import * as Layer from 'effect/Layer';
+import { HostFileProvider } from './host-file.ts';
+import { LaunchdJobProvider } from './job.ts';
+import { localRunner } from './local-runner.ts';
+import { type HostRunner, hostRunnerLayer } from './runner.ts';
+
+export const launchdProviders = (runner: HostRunner = localRunner()) =>
+  Layer.mergeAll(LaunchdJobProvider(), HostFileProvider()).pipe(
+    Layer.provide(hostRunnerLayer(runner)),
+  );

package/src/launchd/runner.ts

@@ -0,0 +1,95 @@
+/**
+ * The one seam between the launchd providers and the host: every file read, file write and
+ * `launchctl` call goes through a HostRunner, and nothing in this directory touches the host any
+ * other way.
+ *
+ * ★ WHY A SEAM AND NOT DIRECT node:fs CALLS. launchd has no SDK — the provider renders a plist and
+ *   drives `launchctl` — so the only way to test the lifecycle without a real launchd (and without
+ *   writing /Library) is to swap the host out. fake-runner.ts is an in-memory host with a scripted
+ *   launchd; local-runner.ts is the real one. The same seam is where a consumer plugs in a runner
+ *   that reaches a host some other way.
+ *
+ * ★ PROMISES, NOT EFFECTS, ON PURPOSE. A consumer writing their own runner implements plain async
+ *   functions; the providers lift them into Effect at the call site (host-effect.ts).
+ */
+import * as Context from 'effect/Context';
+import * as Layer from 'effect/Layer';
+
+/** One finished process. ⛔ `stdout` may carry anything the job's environment holds — never log it. */
+export type ExecResult = {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+};
+
+/**
+ * What `lstat` says about a path. ⚠️ lstat, not stat: a symlink is reported as a symlink, because
+ *   writing through one would change a file this resource never named.
+ */
+export type FileStat = {
+  readonly kind: 'file' | 'directory' | 'symlink' | 'other';
+  /** Permission bits only (`& 0o7777`), never the file-type bits. */
+  readonly mode: number;
+  readonly uid: number;
+  readonly gid: number;
+  readonly size: number;
+};
+
+export type WriteOptions = {
+  /** Permission bits for the final file, applied BEFORE it becomes visible at `path`. */
+  readonly mode: number;
+  /** Numeric owner; omitted means whoever the runner writes as. */
+  readonly uid?: number;
+  /** Numeric group; omitted means the directory's default. */
+  readonly gid?: number;
+};
+
+export type HostUser = { readonly uid: number; readonly gid: number; readonly home: string };
+
+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
+   *   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.
+   */
+  readonly privileged: boolean;
+  /** The uid file writes and launchctl calls run as. */
+  effectiveUid(): number;
+  /** Run a program with an argv — ⛔ never through a shell. */
+  exec(argv: readonly string[]): Promise<ExecResult>;
+  /** File bytes, or `undefined` when nothing is at `path`. */
+  readFile(path: string): Promise<Uint8Array | undefined>;
+  /** lstat, or `undefined` when nothing is at `path`. */
+  stat(path: string): Promise<FileStat | undefined>;
+  /**
+   * Write `bytes` so that `path` holds either the old file or the new one, never a torn mix:
+   * a temporary file in the same directory, mode and owner set on it, then rename(2) over `path`.
+   * ⚠️ The parent directory must exist; creating it would invent an owner and mode nobody declared.
+   */
+  writeFileAtomic(path: string, bytes: Uint8Array, options: WriteOptions): Promise<void>;
+  /** Remove a file. Idempotent: nothing at `path` is success. */
+  removeFile(path: string): Promise<void>;
+  /** A user by name or numeric id, or `undefined` when the host has none. */
+  lookupUser(nameOrId: string): Promise<HostUser | undefined>;
+  /** A group's gid by name or numeric id, or `undefined` when the host has none. */
+  lookupGroup(nameOrId: string): Promise<number | undefined>;
+  /** Wait between launchctl polls. ★ Injected so a test never sleeps for real. */
+  sleep(ms: number): Promise<void>;
+}
+
+/** The Effect service every launchd provider reads its runner from. */
+export class HostRunnerService extends Context.Service<HostRunnerService, HostRunner>()(
+  'homeflare/launchd/HostRunner',
+) {}
+
+/** Provide a runner to the providers: `Layer.provide(hostRunnerLayer(localRunner()))`. */
+export const hostRunnerLayer = (runner: HostRunner): Layer.Layer<HostRunnerService> =>
+  Layer.succeed(HostRunnerService, runner);
+
+/** True when this runner may write root-owned paths and drive the system domain. */
+export const canActAsRoot = (runner: HostRunner): boolean =>
+  runner.privileged || runner.effectiveUid() === 0;

package/src/launchd/secret-tripwire.test.ts

@@ -0,0 +1,110 @@
+/**
+ * The tripwire trips on the names and shapes people type — and stays quiet on the file-path
+ * pattern it tells them to use instead. A tripwire that fired on `*_FILE` would train people to
+ * route around it.
+ */
+import { describe, expect, test } from 'bun:test';
+import { fileSecretProblems, jobSecretProblems } from './secret-tripwire.ts';
+
+/**
+ * ⚠️ ASSEMBLED FROM PARTS ON PURPOSE. Written out whole, this fixture trips gitleaks' `private-key`
+ *   rule in the pre-commit hook — measured 2026-09-21 — even though the body is four letters.
+ */
+const KEY = `${'PRIVATE'} KEY-----`;
+const PEM = [`-----BEGIN OPENSSH ${KEY}`, 'AAAA', `-----END OPENSSH ${KEY}`].join('\n');
+
+describe('environment names', () => {
+  test.each([
+    'API_TOKEN',
+    'VAULT_TOKEN',
+    'TOKEN',
+    'CLIENT_SECRET',
+    'DB_PASSWORD',
+    'SMTP_PASSWD',
+    'OPENAI_API_KEY',
+    'APIKEY',
+    'AWS_SECRET_ACCESS_KEY',
+    'SIGNING_PRIVATE_KEY',
+    'GOOGLE_CREDENTIALS',
+    'api_token',
+  ])('%s trips', (name) => {
+    expect(jobSecretProblems({ [name]: 'value' }, ['/bin/x'])).toHaveLength(1);
+  });
+
+  test.each([
+    'API_TOKEN_FILE',
+    'DB_PASSWORD_PATH',
+    'SSL_CERT_FILE',
+    'TOKENIZER',
+    'HOME',
+    'PATH',
+    'SECRET_DIR',
+    'AWS_ACCESS_KEY_ID',
+    'KEYCHAIN',
+  ])('%s does not', (name) => {
+    expect(jobSecretProblems({ [name]: '/some/path' }, ['/bin/x'])).toEqual([]);
+  });
+
+  test('a private key in any variable trips', () => {
+    expect(jobSecretProblems({ INNOCENT: PEM }, ['/bin/x'])).toHaveLength(1);
+  });
+});
+
+describe('arguments', () => {
+  test.each([
+    [['/bin/x', '--token=abc']],
+    [['/bin/x', '--vault-token=abc']],
+    [['/bin/x', '-password=abc']],
+    [['/bin/x', '--api-key=abc']],
+    [['/bin/x', '--token', 'abc']],
+    [['/bin/x', '--client-secret', 'abc']],
+    [['/bin/x', PEM]],
+  ])('%j trips', (argv) => {
+    expect(jobSecretProblems(undefined, argv)).toHaveLength(1);
+  });
+
+  test.each([
+    [['/bin/x', '--token-file=/run/secret']],
+    [['/bin/x', '--token-file', '/run/secret']],
+    [['/bin/x', '--password-file', '/run/secret']],
+    [['/bin/x', '--token']],
+    [['/bin/x', '--config', '/etc/x.yml']],
+  ])('%j does not', (argv) => {
+    expect(jobSecretProblems(undefined, argv)).toEqual([]);
+  });
+
+  test('a refusal never echoes the secret it found', () => {
+    const [problem] = jobSecretProblems(undefined, [
+      '/bin/x',
+      '--token=hunter2',
+      '--secret',
+      'hunter3',
+    ]);
+    expect(problem).not.toContain('hunter');
+    expect(jobSecretProblems({ API_TOKEN: 'hunter4' }, ['/bin/x']).join()).not.toContain('hunter4');
+  });
+
+  test('a private key anywhere in extraKeys trips, by path, without echoing it', () => {
+    const found = jobSecretProblems(undefined, ['/bin/x'], {
+      Sockets: { Listener: [{ SockServiceName: '9000' }, { Blob: `x\n${PEM}` }] },
+    });
+    expect(found).toHaveLength(1);
+    expect(found[0]).toContain('extraKeys.Sockets.Listener[1].Blob');
+    expect(found[0]).not.toContain('BEGIN');
+  });
+
+  test('every refusal names the alternative', () => {
+    expect(jobSecretProblems({ API_TOKEN: 'x' }, ['/bin/x']).join()).toContain('openbao-agent');
+  });
+});
+
+describe('file content', () => {
+  test('a PEM private key trips; a certificate or public key does not', () => {
+    expect(fileSecretProblems(`config\n${PEM}\n`)).toHaveLength(1);
+    expect(fileSecretProblems(`-----BEGIN RSA ${KEY}\n`)).toHaveLength(1);
+    expect(
+      fileSecretProblems('-----BEGIN CERTIFICATE-----\nMIIB\n-----END CERTIFICATE-----\n'),
+    ).toEqual([]);
+    expect(fileSecretProblems('ssh-ed25519 AAAAC3Nza example\n')).toEqual([]);
+  });
+});

package/src/launchd/secret-tripwire.ts

@@ -0,0 +1,81 @@
+/**
+ * A tripwire for the obvious ways a secret ends up in Alchemy state through these providers.
+ *
+ * ⛔ WHY IT EXISTS. Alchemy persists every prop UNENCRYPTED in its state store — the same reason
+ *   the OpenBao families are metadata-only (openbao/policy.ts). A LaunchdJob's `environment` and
+ *   `programArguments`, and a HostFile's `content`, are props. A token declared there is a token
+ *   copied into the state store, into every plan diff, and into the plist or file on disk.
+ * ★ THE ALTERNATIVE, NAMED IN EVERY REFUSAL: let a secret renderer (openbao-agent, or any other)
+ *   write the secret to a root-owned file, and declare only its PATH — `FOO_TOKEN_FILE=/path`,
+ *   `--token-file /path`. The job reads the file at start; the state holds a path.
+ *
+ * ⚠️ A TRIPWIRE, NOT A SCANNER. It catches the names and shapes people actually type. A token in
+ *   an innocently named variable passes; nothing here can make a secret safe to declare.
+ */
+import type { PlistDict, PlistValue } from './plist.ts';
+
+const 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).';
+
+/** Names that end in a word meaning "this is the secret itself". `*_FILE`, `*_PATH` never match. */
+const SECRET_NAME =
+  /(?:^|_)(?:TOKEN|SECRET|PASSWORD|PASSWD|PASSPHRASE|API_?KEY|ACCESS_KEY|PRIVATE_KEY|SECRET_KEY|CREDENTIALS?)$/i;
+
+/** `--token=…` / `-password=…` style flags carrying their value inline. */
+const INLINE_FLAG = /^--?[a-z0-9-]*(?:token|password|passwd|passphrase|secret|api-?key)=./i;
+
+/** 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-----/;
+
+/** Paths of every string leaf in a plist value holding a private key. */
+const keyLeaves = (value: PlistValue, path: string): string[] => {
+  if (typeof value === 'string') return PRIVATE_KEY.test(value) ? [path] : [];
+  if (Array.isArray(value)) {
+    return (value as readonly PlistValue[]).flatMap((item, index) =>
+      keyLeaves(item, `${path}[${String(index)}]`),
+    );
+  }
+  if (typeof value === 'object' && value !== null) {
+    return Object.entries(value).flatMap(([key, item]) => keyLeaves(item, `${path}.${key}`));
+  }
+  return [];
+};
+
+/**
+ * Refusals for a job's environment, argv and extraKeys. Empty means nothing tripped.
+ * ★ extraKeys too: it is a prop like the others, so it lands in state just the same.
+ */
+export const jobSecretProblems = (
+  environment: Readonly<Record<string, string>> | undefined,
+  argv: readonly string[],
+  extraKeys?: PlistDict,
+): string[] => {
+  const found: string[] = [];
+  for (const [name, value] of Object.entries(environment ?? {})) {
+    if (SECRET_NAME.test(name))
+      found.push(`environment ${name} looks like a secret: ${ALTERNATIVE}`);
+    else if (PRIVATE_KEY.test(value))
+      found.push(`environment ${name} holds a private key: ${ALTERNATIVE}`);
+  }
+  for (const [index, arg] of argv.entries()) {
+    // ⛔ Never echo the argument itself: if it IS a secret, the refusal would print it.
+    if (INLINE_FLAG.test(arg)) {
+      found.push(`programArguments[${String(index)}] passes a secret inline: ${ALTERNATIVE}`);
+    } else if (BARE_FLAG.test(arg) && index + 1 < argv.length) {
+      found.push(`programArguments[${String(index + 1)}] follows a secret flag: ${ALTERNATIVE}`);
+    } else if (PRIVATE_KEY.test(arg)) {
+      found.push(`programArguments[${String(index)}] holds a private key: ${ALTERNATIVE}`);
+    }
+  }
+  for (const path of keyLeaves(extraKeys ?? {}, 'extraKeys')) {
+    found.push(`${path} holds a private key: ${ALTERNATIVE}`);
+  }
+  return found;
+};
+
+/** Refusals for a HostFile's content. */
+export const fileSecretProblems = (content: string): string[] =>
+  PRIVATE_KEY.test(content) ? [`content holds a private key: ${ALTERNATIVE}`] : [];