@homeflare/alchemy 0.1.0

package/src/openbao/forgejo-bootstrap.ts

@@ -0,0 +1,181 @@
+/**
+ * The forgejo-provision service account: created once, by a person, with its password handed
+ * straight to the Forgejo engine's role and nowhere else.
+ *
+ * ★ TIM'S CALL, 2026-09-14: "Random password, piped", and membership of the HomeFlare Owners team
+ *   (house/forgejo, Forgejo.TeamMember). Forgejo has no service-account type and no app.ini setting
+ *   that creates users — the bot type is database-only (codeberg issue 8136) — so this is an
+ *   ordinary user made by `forgejo admin user create`.
+ *
+ * ⛔ AN AGENT DOES NOT RUN THIS. Creating an account is a human step (32-forgejo-provision.hcl).
+ *   Everything around it is not: the engine, its config, the team membership and the mint proof.
+ *
+ * ⛔ THE PASSWORD EXISTS IN THIS PROCESS AND IN ONE OPENBAO WRITE, AND NOWHERE ELSE.
+ *   - Forgejo generates it (`--random-password`), so it is never in argv, where `ps` shows it.
+ *   - Its stdout line is parsed and never echoed (forgejo-bootstrap-parse.ts).
+ *   - It lands in `forgejo/roles/provision` as `mint_password`, which the engine never returns on a
+ *     read (plugin-forgejo path_roles.go:63-71, :219-227).
+ *   - It is never a file, an environment variable, a log line or an Alchemy prop.
+ *
+ * ★ EVERYTHING THAT CAN FAIL IS CHECKED BEFORE THE ACCOUNT EXISTS. An account whose password was
+ *   lost between the CLI and OpenBao is the one failure a rerun cannot fix. So the preflight runs
+ *   first, and if the write still fails after that, the account is deleted again so a rerun starts
+ *   clean.
+ */
+import * as Effect from 'effect/Effect';
+import { baoCall, baoRead, baoWrite } from './bao-http.ts';
+import {
+  FORGEJO_CONFIG,
+  FORGEJO_WORK_PATH,
+  readCreateOutput,
+  runningForgejoBinary,
+  tailOf,
+  usernamesFrom,
+} from './forgejo-bootstrap-parse.ts';
+
+export const PROVISION_USER = 'forgejo-provision';
+/** `NO_REPLY_ADDRESS` in hosts/macmini/forgejo/app.ini:117 — a service account's mail goes nowhere. */
+const PROVISION_EMAIL = `${PROVISION_USER}@noreply.lab.example.com`;
+export const ROLE_PATH = 'forgejo/roles/provision';
+
+/**
+ * ★ THE SCOPES ARE WHAT house/forgejo WRITES TODAY. Org labels, teams and org secrets need
+ *   `write:organization`; repositories, webhooks and branch protection need `write:repository`.
+ *   Membership decides what the tokens can reach, and the scopes cap it.
+ * ⚠️ FORGEJO TOKENS NEVER EXPIRE ON THE SERVER. The TTL is OpenBao's lease, and revoking the lease is
+ *   the only kill switch (path_roles.go:206-207).
+ */
+const ROLE = { max_ttl: '1h', scopes: 'write:organization,write:repository', ttl: '15m' } as const;
+
+const refuse = (message: string) => Effect.fail(new Error(message));
+const say = (line: string) => Effect.sync(() => process.stdout.write(`${line}\n`));
+
+/** Run a command and collect everything it printed. ⛔ argv must never carry a secret. */
+const run = (argv: readonly string[]) =>
+  Effect.tryPromise({
+    catch: (cause) => new Error(`${argv.slice(0, 4).join(' ')} could not run: ${String(cause)}`),
+    try: async () => {
+      const child = Bun.spawn([...argv], { stderr: 'pipe', stdin: 'ignore', stdout: 'pipe' });
+      const [stdout, stderr, code] = await Promise.all([
+        new Response(child.stdout).text(),
+        new Response(child.stderr).text(),
+        child.exited,
+      ]);
+      return { code, stderr, stdout };
+    },
+  });
+
+export const bootstrapProvisionAccount = Effect.gen(function* () {
+  // ── 1. OpenBao: the engine is configured, the role is absent, and this token may create it.
+  const config = yield* baoRead('forgejo/config');
+  if (typeof config?.['api_base_url'] !== 'string') {
+    return yield* refuse('forgejo/config has no api_base_url. Configure the engine first.');
+  }
+  const existing = yield* baoRead(ROLE_PATH);
+  if (existing !== undefined) {
+    return yield* refuse(
+      `${ROLE_PATH} already exists (mint_user ${String(existing['mint_user'])}). Nothing to do.`,
+    );
+  }
+  const capabilities = yield* baoCall('write', 'POST', 'sys/capabilities-self', {
+    paths: [ROLE_PATH],
+  });
+  const granted = capabilities?.[ROLE_PATH];
+  if (!Array.isArray(granted) || !granted.some((c) => c === 'create' || c === 'root')) {
+    return yield* refuse(
+      `this BAO_TOKEN cannot create ${ROLE_PATH} (capabilities: ${JSON.stringify(granted)}).`,
+    );
+  }
+
+  // ── 2. Forgejo: the running binary, and no account by that name yet.
+  const ps = yield* run(['ps', '-axo', 'command']);
+  const binary = runningForgejoBinary(ps.stdout);
+  if (binary === undefined) {
+    return yield* refuse(
+      'no running `forgejo web` found. Run this on the mini, where Forgejo runs.',
+    );
+  }
+  const cli = (subcommand: string, ...args: string[]) =>
+    run([
+      binary,
+      'admin',
+      'user',
+      subcommand,
+      '--work-path',
+      FORGEJO_WORK_PATH,
+      '--config',
+      FORGEJO_CONFIG,
+      ...args,
+    ]);
+  const listUsers = Effect.gen(function* () {
+    const listed = yield* cli('list');
+    if (listed.code !== 0) {
+      return yield* refuse(
+        `forgejo admin user list exited ${listed.code}: ${tailOf(listed.stderr)}`,
+      );
+    }
+    return yield* Effect.try({
+      catch: (cause) => (cause instanceof Error ? cause : new Error(String(cause))),
+      try: () => usernamesFrom(listed.stdout),
+    });
+  });
+  if ((yield* listUsers).includes(PROVISION_USER)) {
+    return yield* refuse(
+      `Forgejo already has ${PROVISION_USER} but OpenBao has no role for it, so its password is ` +
+        'unknown. Delete that account deliberately, then rerun.',
+    );
+  }
+
+  /** ⛔ Only an account THIS run just created is ever removed, and only when its password is lost. */
+  const rollback = (reason: string) =>
+    Effect.gen(function* () {
+      if (!(yield* listUsers).includes(PROVISION_USER)) return;
+      const removed = yield* cli('delete', '--username', PROVISION_USER);
+      yield* say(
+        removed.code === 0
+          ? `  rolled back: deleted ${PROVISION_USER}, because ${reason}`
+          : `  ⛔ ROLLBACK FAILED (${tailOf(removed.stderr)}). ${PROVISION_USER} exists with a ` +
+              'password nobody holds. Delete it by hand before rerunning.',
+      );
+    });
+
+  // ── 3. The one step that makes a secret.
+  const created = yield* cli(
+    'create',
+    '--username',
+    PROVISION_USER,
+    '--email',
+    PROVISION_EMAIL,
+    '--fullname',
+    'Forgejo provision (OpenBao engine)',
+    '--random-password',
+    '--random-password-length',
+    '40',
+    '--must-change-password=false',
+  );
+  const output = readCreateOutput(created.stdout, PROVISION_USER);
+  for (const line of output.rest) yield* say(`  forgejo: ${line}`);
+  const password = output.password;
+  if (created.code !== 0 || !output.created || password === undefined) {
+    const reason = `create exited ${created.code} (${tailOf(created.stderr)})`;
+    yield* rollback(reason);
+    return yield* refuse(`${PROVISION_USER} was not created cleanly: ${reason}`);
+  }
+
+  // ── 4. Straight into the engine, then read back rather than trusting the write.
+  yield* baoWrite('PUT', ROLE_PATH, {
+    ...ROLE,
+    mint_password: password,
+    mint_user: PROVISION_USER,
+  }).pipe(Effect.tapError((error) => rollback(`the OpenBao write failed: ${error.message}`)));
+  const role = yield* baoRead(ROLE_PATH);
+  if (role?.['mint_user'] !== PROVISION_USER || role['mint_password_set'] !== true) {
+    return yield* refuse(
+      `${ROLE_PATH} wrote cleanly but reads back ${JSON.stringify(role)}. Inspect it before retrying.`,
+    );
+  }
+  yield* say(
+    `ok: ${PROVISION_USER} created, and ${ROLE_PATH} holds its password (write-only). ` +
+      `Scopes ${ROLE.scopes}, lease ${ROLE.ttl}, max ${ROLE.max_ttl}.`,
+  );
+});

package/src/openbao/index.ts

@@ -0,0 +1,17 @@
+/**
+ * OpenBao providers for Alchemy.
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API, AND IT IS DELIBERATELY SMALLER THAN THE DIRECTORY.
+ *   These are the symbols a real stack consumes; the rest of the files are internals a
+ *   provider needs but a consumer should not depend on. An `export *` here would publish
+ *   every helper as API and make the next refactor a breaking change.
+ * ★ Anything unlisted is still reachable by path if you genuinely need it — that is a
+ *   deliberate, visible act rather than an accident of barrelling.
+ */
+export { BaoAuthRoleProvider } from './auth-role.ts';
+export { BaoCloudflareRoleProvider } from './cloudflare-role.ts';
+export { BaoMountProvider } from './mount.ts';
+export { BaoPkiRoleProvider } from './pki-role.ts';
+export { BaoPolicy, BaoPolicyProvider } from './policy.ts';
+export { BaoProxmoxRole, BaoProxmoxRoleProvider } from './proxmox-role.ts';
+export { BaoSshRoleProvider } from './ssh-role.ts';

package/src/openbao/mount-form.ts

@@ -0,0 +1,147 @@
+import { sha256 } from './digest.ts';
+
+/** Mount path without a trailing slash — props and `sys/mounts/<path>` use this shape. */
+export const mountPath = (path: string) => path.replace(/\/+$/, '');
+
+const DURATION = /^(\d+)([smhd])$/;
+
+/** Parse a Vault duration string (`15m`, `768h`, `0`) to seconds. */
+export const parseDuration = (text: string): number | undefined => {
+  const trimmed = text.trim();
+  if (trimmed === '0') return 0;
+  const match = DURATION.exec(trimmed);
+  if (match === null) return undefined;
+  const amount = Number(match[1]);
+  switch (match[2]) {
+    case 's':
+      return amount;
+    case 'm':
+      return amount * 60;
+    case 'h':
+      return amount * 3600;
+    case 'd':
+      return amount * 86400;
+    default:
+      return undefined;
+  }
+};
+
+/** Seconds from live JSON (`2764800`) or a duration prop (`768h`). */
+export const ttlSeconds = (value: unknown): number | undefined => {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string') return parseDuration(value);
+  return undefined;
+};
+
+export interface BaoMountProps {
+  /** Mount path without trailing slash, as `sys/mounts/<path>` takes it. */
+  path: string;
+  /** Secrets engine type, e.g. `kv`, `pki`, `openbao-plugin-secrets-cloudflare`. */
+  type: string;
+  /** Human description — tuned via `sys/mounts/<path>/tune`, as apply-roles.py describe_mounts does. */
+  description?: string;
+  /** Default lease TTL, e.g. `768h`. */
+  defaultLeaseTtl?: string;
+  /** Max lease TTL, e.g. `8760h`. */
+  maxLeaseTtl?: string;
+  /** KV only — sent as `options.version` on enable, as `-version=2` was. Immutable after create. */
+  version?: 1 | 2;
+}
+
+export interface BaoMountAttributes {
+  path: string;
+  type: string;
+  description: string;
+  defaultLeaseTtl: string;
+  maxLeaseTtl: string;
+  /** SHA-256 of the managed fields — safe to persist; see policy.ts. */
+  digest: string;
+}
+
+const configOf = (live: Record<string, unknown>) =>
+  typeof live['config'] === 'object' && live['config'] !== null
+    ? (live['config'] as Record<string, unknown>)
+    : {};
+
+const text = (value: unknown) => (typeof value === 'string' ? value : '');
+
+const ttlProp = (seconds: number | undefined, fallback = '') => {
+  if (seconds === undefined) return fallback;
+  if (seconds % 86400 === 0) return `${String(seconds / 86400)}d`;
+  if (seconds % 3600 === 0) return `${String(seconds / 3600)}h`;
+  if (seconds % 60 === 0) return `${String(seconds / 60)}m`;
+  return `${String(seconds)}s`;
+};
+
+export const attributesOf = (
+  props: BaoMountProps,
+  live: Record<string, unknown>,
+): BaoMountAttributes => {
+  const config = configOf(live);
+  const defaultLeaseTtl = ttlProp(ttlSeconds(config['default_lease_ttl']));
+  const maxLeaseTtl = ttlProp(ttlSeconds(config['max_lease_ttl']));
+  const attrs = {
+    path: mountPath(props.path),
+    type: text(live['type']) || props.type,
+    description: text(live['description']),
+    defaultLeaseTtl,
+    maxLeaseTtl,
+  };
+  return { ...attrs, digest: sha256(JSON.stringify(attrs)) };
+};
+
+/** `sys/mounts/<path>` — read, enable and disable all address the mount here. */
+export const readPath = (path: string) => `sys/mounts/${mountPath(path)}`;
+
+/**
+ * ★ NO TRAILING SLASH NEEDED ON THE WIRE. `bao secrets tune` appended one itself; the server's
+ *   route `mounts/(?P<path>.+?)/tune$` captures the bare path and `sanitizePath` appends the slash
+ *   OpenBao stores in sys/mounts (openbao v2.6.2 vault/logical_system_paths.go:4248,
+ *   vault/logical_system.go:4825-4833).
+ */
+export const tunePath = (path: string) => `${readPath(path)}/tune`;
+
+/**
+ * The enable body. `-version=2` on the CLI became `options.version = "2"` (openbao v2.6.2
+ * command/secrets_enable.go:278 into api MountInput.Options), so that is what is sent.
+ *
+ * ⚠️ DESCRIPTION AND TTLs ARE NOT SENT HERE. reconcile tunes them straight after the enable,
+ *   exactly as the CLI path did, so a create and an update converge through the same call.
+ */
+export const enableBody = (props: BaoMountProps): Record<string, unknown> =>
+  props.version === 2 ? { options: { version: '2' }, type: props.type } : { type: props.type };
+
+/**
+ * The tune body — only the fields the declaration names.
+ *
+ * ★ AN OMITTED FIELD IS LEFT ALONE. The server reads an absent TTL as "" and keeps the mount's
+ *   current value for "" (vault/logical_system.go:1614-1630), and applies `description` only when
+ *   present (:1725). The CLI sent unset TTL flags as "" and set description only when given
+ *   (command/secrets_tune.go Visit), so omitting them is the same request.
+ */
+export const tuneBody = (props: BaoMountProps): Record<string, string> => {
+  const body: Record<string, string> = {};
+  if (props.description !== undefined) body['description'] = props.description;
+  if (props.defaultLeaseTtl !== undefined) body['default_lease_ttl'] = props.defaultLeaseTtl;
+  if (props.maxLeaseTtl !== undefined) body['max_lease_ttl'] = props.maxLeaseTtl;
+  return body;
+};
+
+const sameTtl = (want: string | undefined, have: string) => {
+  if (want === undefined) return true;
+  const wantSeconds = ttlSeconds(want);
+  const haveSeconds = ttlSeconds(have);
+  return wantSeconds !== undefined && wantSeconds === haveSeconds;
+};
+
+/** True when live already matches the declaration on every managed field. */
+export const matches = (attributes: BaoMountAttributes, props: BaoMountProps) =>
+  attributes.type === props.type &&
+  (props.description === undefined || attributes.description === props.description) &&
+  sameTtl(props.defaultLeaseTtl, attributes.defaultLeaseTtl) &&
+  sameTtl(props.maxLeaseTtl, attributes.maxLeaseTtl);
+
+export const wantsTune = (props: BaoMountProps) =>
+  props.description !== undefined ||
+  props.defaultLeaseTtl !== undefined ||
+  props.maxLeaseTtl !== undefined;

package/src/openbao/mount-wire.test.ts

@@ -0,0 +1,108 @@
+/**
+ * Bao.Mount's calls against a fake. The part worth pinning is the MISSING mount: OpenBao answers a
+ * read of one with 400, not 404 (vault/logical_system.go:1171-1178), and only the mount table may
+ * turn that into "absent".
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { BaoError } from './bao-status.ts';
+import { type Reply, type Seen, run, runFailure, withFake } from './fake-bao.ts';
+import { disableMount, enableMount, readMountData, tuneMount } from './mount-wire.ts';
+
+const NO_MOUNT = { json: { errors: ['No secret engine mount at zz-new/'] }, status: 400 };
+const table = (...paths: string[]) => ({
+  json: { data: Object.fromEntries(paths.map((path) => [path, { type: 'kv' }])) },
+  status: 200,
+});
+
+/** Answer the mount read with `mount`, and the mount-table listing with `listing`. */
+const routes = (mount: Reply, listing: Reply) => (seen: Seen) =>
+  seen.path === '/v1/sys/mounts' ? listing : mount;
+
+const statusOf = async (error: Promise<unknown>) => {
+  const settled = await error;
+  assert.ok(settled instanceof BaoError);
+  return settled.status;
+};
+
+describe('readMountData', () => {
+  it('reads a mount that exists, without consulting the table', async () => {
+    const reply = { json: { data: { config: {}, type: 'pki' } }, status: 200 };
+    await withFake(routes(reply, table()), async (bao) => {
+      const data = await run({ BAO_ADDR: bao.address }, readMountData('pki'));
+      assert.equal(data?.['type'], 'pki');
+      assert.deepEqual(
+        bao.seen.map((seen) => seen.path),
+        ['/v1/sys/mounts/pki'],
+      );
+    });
+  });
+
+  it("reads a missing mount as absent once the table confirms OpenBao's 400", async () => {
+    await withFake(routes(NO_MOUNT, table('kv/', 'pki/')), async (bao) => {
+      assert.equal(await run({ BAO_ADDR: bao.address }, readMountData('zz-new/')), undefined);
+      assert.deepEqual(
+        bao.seen.map((seen) => seen.path),
+        ['/v1/sys/mounts/zz-new', '/v1/sys/mounts'],
+      );
+    });
+  });
+
+  it('keeps the 400 when the table lists the mount after all', async () => {
+    await withFake(routes(NO_MOUNT, table('zz-new/')), async (bao) => {
+      const error = runFailure({ BAO_ADDR: bao.address }, readMountData('zz-new'));
+      assert.equal(await statusOf(error), 400);
+    });
+  });
+
+  it('keeps the 400 when the table read is refused', async () => {
+    const refused = { json: { errors: ['permission denied'] }, status: 403 };
+    await withFake(routes(NO_MOUNT, refused), async (bao) => {
+      const error = runFailure({ BAO_ADDR: bao.address }, readMountData('zz-new'));
+      assert.equal(await statusOf(error), 400);
+    });
+  });
+
+  it('fails a refused mount read (403) without consulting the table', async () => {
+    const refused = { json: { errors: ['permission denied'] }, status: 403 };
+    await withFake(routes(refused, table()), async (bao) => {
+      const error = runFailure({ BAO_ADDR: bao.address }, readMountData('kv'));
+      assert.equal(await statusOf(error), 403);
+      assert.equal(bao.seen.length, 1);
+    });
+  });
+});
+
+describe('enable, tune, disable', () => {
+  it('sends the endpoints and bodies the CLI client sent', async () => {
+    await withFake(
+      () => ({ status: 204 }),
+      async (bao) => {
+        const env = { BAO_ADDR: bao.address };
+        const props = { defaultLeaseTtl: '768h', path: 'kv/', type: 'kv', version: 2 as const };
+        await run(env, enableMount(props));
+        await run(env, tuneMount(props));
+        await run(env, disableMount('kv'));
+        const calls = bao.seen.map((seen) => [seen.method, seen.path, seen.body]);
+        assert.deepEqual(calls, [
+          ['POST', '/v1/sys/mounts/kv', JSON.stringify({ options: { version: '2' }, type: 'kv' })],
+          ['POST', '/v1/sys/mounts/kv/tune', JSON.stringify({ default_lease_ttl: '768h' })],
+          ['DELETE', '/v1/sys/mounts/kv', ''],
+        ]);
+      },
+    );
+  });
+
+  it('fails a refused enable with OpenBao errors', async () => {
+    await withFake(
+      () => ({ json: { errors: ['path is already in use at kv/'] }, status: 400 }),
+      async (bao) => {
+        const error = runFailure(
+          { BAO_ADDR: bao.address },
+          enableMount({ path: 'kv', type: 'kv' }),
+        );
+        assert.equal(await statusOf(error), 400);
+      },
+    );
+  });
+});

package/src/openbao/mount-wire.ts

@@ -0,0 +1,79 @@
+/**
+ * The OpenBao calls Bao.Mount makes — read one mount, enable, tune, disable. Split from mount.ts so
+ * the classification of a MISSING mount can be tested against a fake server.
+ *
+ * ★ ENDPOINTS, READ FROM openbao v2.6.2 api/sys_mounts.go — the client the CLI used:
+ *     read     GET    sys/mounts/<path>        (MountInfo, :254)  — what `bao read sys/mounts/<path>` hit
+ *     enable   POST   sys/mounts/<path>        (Mount, :57)       — `bao secrets enable`
+ *     tune     POST   sys/mounts/<path>/tune   (TuneMount, :201)  — `bao secrets tune`
+ *     disable  DELETE sys/mounts/<path>        (Unmount, :79)     — `bao secrets disable`
+ */
+import * as Effect from 'effect/Effect';
+import { baoDelete, baoRead, baoWrite } from './bao-http.ts';
+import { BaoError } from './bao-status.ts';
+import {
+  type BaoMountProps,
+  enableBody,
+  mountPath,
+  readPath,
+  tuneBody,
+  tunePath,
+} from './mount-form.ts';
+
+/**
+ * Confirm a mount is absent from the mount table, or give back the error that asked.
+ *
+ * ⛔ A MISSING MOUNT IS NOT A 404, IT IS A 400 — AND THAT MADE A NEW MOUNT UNCREATABLE, SILENTLY,
+ *   THE SAME WAY A NEW POLICY WAS (b3c18a33e). `handleReadMount` answers a path with no mount with a
+ *   bare error response, "No secret engine mount at <path>" (vault/logical_system.go:1171-1178), and
+ *   RespondErrorCommon turns an error response with no coded error into 400
+ *   (sdk/logical/response_util.go). The CLI therefore exited 2 with that text, which was not
+ *   `No value found at`, so every read of an undeclared-yet mount FAILED and reconcile never
+ *   reached `secrets enable`. All four declared mounts already exist, which is the only reason
+ *   nothing broke. REASONED FROM SOURCE, NOT MEASURED — no read of a missing mount was run.
+ * ★ SO A 400 IS SETTLED BY A SECOND, STATUS-CLASSIFIED QUESTION rather than by matching that text:
+ *   `GET sys/mounts` lists the namespace's mount table, keyed `<path>/`. Only a 200 table WITHOUT
+ *   the key is absence. A listed mount, a refused listing, or a 404 listing leaves the original 400
+ *   standing — "I could not tell" is an error, never a create.
+ * ⚠️ THE LISTING NEEDS `read` ON `sys/mounts`. The admin lane has it
+ *   (policies/homeflare-admin/live-captured-2026-09-02.hcl:20). A narrower token still fails, which
+ *   is what it did before.
+ */
+const absentFromTable = (path: string, asked: BaoError) =>
+  baoRead('sys/mounts').pipe(
+    // ⚠️ A listing that fails keeps the 400, and says why it could not settle it.
+    Effect.mapError(
+      (listing) =>
+        new BaoError(asked.status, asked.method, asked.path, [
+          ...asked.errors,
+          `sys/mounts could not confirm the mount is absent: ${listing.message}`,
+        ]),
+    ),
+    Effect.flatMap((table) =>
+      table !== undefined && !Object.hasOwn(table, `${mountPath(path)}/`)
+        ? Effect.succeed(undefined)
+        : Effect.fail(asked),
+    ),
+  );
+
+/** One mount's config (`type`, `description`, `config.*_lease_ttl`), or undefined when absent. */
+export const readMountData = (path: string) =>
+  baoRead(readPath(path)).pipe(
+    Effect.catchIf(
+      (error) => error.status === 400,
+      (error) => absentFromTable(path, error),
+    ),
+  );
+
+export const enableMount = (props: BaoMountProps) =>
+  baoWrite('POST', readPath(props.path), enableBody(props));
+
+export const tuneMount = (props: BaoMountProps) =>
+  baoWrite('POST', tunePath(props.path), tuneBody(props));
+
+/**
+ * ⚠️ THERE IS NO FORCE. The old delete ran `bao secrets disable -force`, and v2.6.2's
+ *   command/secrets_disable.go defines no `-force` flag, so that argv would have been refused at
+ *   flag parsing. `Unmount` is a plain DELETE (api/sys_mounts.go:79); nothing else was ever sent.
+ */
+export const disableMount = (path: string) => baoDelete(readPath(path));

package/src/openbao/mount.ts

@@ -0,0 +1,132 @@
+/**
+ * An OpenBao secrets engine mount — path, type, description and lease TTLs.
+ *
+ * ⛔ NO SECRET IN PROPS OR ATTRIBUTES — see policy.ts for why. This declares mount
+ *   SHAPE only: names, types, TTL strings and a digest. KV values and CA material live
+ *   in OpenBao, not Alchemy state.
+ *
+ * ★ `defaultRemovalPolicy: 'retain'` — disabling a mount destroys every secret under it.
+ *   Opt in with `.pipe(RemovalPolicy.destroy())`; see resource.ts in house/proxmox.
+ */
+import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import {
+  type BaoMountAttributes,
+  type BaoMountProps,
+  attributesOf,
+  matches,
+  mountPath,
+  wantsTune,
+} from './mount-form.ts';
+import { disableMount, enableMount, readMountData, tuneMount } from './mount-wire.ts';
+
+export type { BaoMountAttributes, BaoMountProps };
+
+export interface BaoMount extends Resource<
+  'Bao.Mount',
+  BaoMountProps,
+  BaoMountAttributes,
+  never,
+  HttpClient.HttpClient
+> {}
+
+export const BaoMount = Resource<BaoMount>('Bao.Mount', {
+  defaultRemovalPolicy: 'retain',
+});
+
+const readMount = (props: BaoMountProps) =>
+  Effect.gen(function* () {
+    const live = yield* readMountData(props.path);
+    if (live === undefined) return undefined;
+    return attributesOf(props, live);
+  });
+
+export const BaoMountProvider = () =>
+  Provider.effect(
+    BaoMount,
+    Effect.succeed(
+      BaoMount.Provider.of({
+        /**
+         * ⛔ `bao secrets list` IS NOT A LIST OF THINGS THIS OWNS. Every mount in the
+         *   namespace answers, including ones created by hand at bringup. Returning them
+         *   would invite Alchemy to adopt — and then disable — mounts it never created.
+         * ⚠️ mount-wire.ts does read that listing, for one question only: whether a mount a 400
+         *   named is really absent. It never becomes a list of resources.
+         */
+        list: () => Effect.succeed([]),
+
+        read: Effect.fn(function* ({ olds }) {
+          return yield* readMount(olds);
+        }),
+
+        diff: Effect.fn(function* ({ news, output }) {
+          if (output === undefined || !isResolved(news)) return undefined;
+          const live = yield* readMount(news);
+          if (live === undefined) return { action: 'update' } as const;
+          /**
+           * ⛔ A CHANGED `type` IS A REPLACE, AND THIS FAMILY'S DELETE IS A MOUNT DISABLE — the
+           *   destruction of every secret under the mount. `kv/` is the estate's entire
+           *   secret shelf, so the question "does `retain` guard the delete half of a REPLACE, or
+           *   only an orphan?" is the difference between a typo and a catastrophe.
+           * ★ IT GUARDS BOTH — VERIFIED IN ALCHEMY'S OWN SOURCE, not assumed. Apply.ts:2164-2173:
+           *   "Honor `retain` for the old generation of a replacement, mirroring the orphan-delete
+           *   path above", with `retainOldGeneration = node.removalPolicy === 'retain'`, and when
+           *   it is true the engine logs "Retaining replaced resource (removal policy: retain)"
+           *   and skips the delete entirely. Every mount this package declares carries the retain
+           *   default (see the ★ on the resource below), so a wrong `type` string cannot disable a
+           *   live mount. What it CAN do is try to enable a second mount at an occupied path,
+           *   which OpenBao refuses loudly — a failed deploy, not a lost shelf.
+           * ⚠️ THAT SAFETY IS THE DECORATION'S, NOT THIS LINE'S. A caller who opts into
+           *   `.pipe(RemovalPolicy.destroy())` gets the destructive replace, which is the correct
+           *   meaning of opting in and is worth knowing before you type it on a mount.
+           */
+          if (live.type !== news.type) return { action: 'replace' } as const;
+          if (matches(live, news)) return { action: 'noop' } as const;
+          return { action: 'update' } as const;
+        }),
+
+        /**
+         * ★ A REFUSED ENABLE OR TUNE FAILS THE EFFECT WITH OpenBao's OWN `errors`, naming the
+         *   method and path — the job the per-command exit-code checks used to do by hand.
+         */
+        reconcile: Effect.fn(function* ({ news }) {
+          let live = yield* readMount(news);
+          if (live === undefined) {
+            yield* enableMount(news);
+            if (wantsTune(news)) yield* tuneMount(news);
+          } else if (!matches(live, news)) {
+            if (live.type !== news.type) {
+              return yield* Effect.die(
+                new Error(
+                  `Bao.Mount ${mountPath(news.path)}: live type ${live.type} != ${news.type}. ` +
+                    'Secrets engine type is immutable — replace manually.',
+                ),
+              );
+            }
+            yield* tuneMount(news);
+          }
+          live = yield* readMount(news);
+          if (live === undefined) {
+            return yield* Effect.die(
+              new Error(
+                `Bao.Mount ${mountPath(news.path)}: write returned no error but the mount is still absent.`,
+              ),
+            );
+          }
+          return live;
+        }),
+
+        /**
+         * ⛔ DISABLING A MOUNT DESTROYS EVERY SECRET UNDER IT. Idempotent as Alchemy
+         *   requires — already gone is success — but retain is the default for a reason.
+         */
+        delete: Effect.fn(function* ({ output }) {
+          yield* disableMount(output.path);
+          return undefined;
+        }),
+      }),
+    ),
+  );