@homeflare/alchemy 0.3.2 → 0.4.1

package/src/openbao/auth-method-wire.test.ts

@@ -0,0 +1,127 @@
+/**
+ * Bao.AuthMethod's calls against a fake. A missing method is a 400, not a 404 —
+ * the same trap as secrets mounts (mount-wire.ts). Only the auth table may
+ * turn that 400 into "absent".
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  disableAuthMethod,
+  enableAuthMethod,
+  readAuthMethodData,
+  tuneAuthMethod,
+} from './auth-method-wire.ts';
+import { BaoError } from './bao-status.ts';
+import { type Reply, type Seen, run, runFailure, withFake } from './fake-bao.ts';
+
+const NO_AUTH = { json: { errors: ['No auth engine at approle-new/'] }, status: 400 };
+const table = (...paths: string[]) => ({
+  json: { data: Object.fromEntries(paths.map((path) => [path, { type: 'approle' }])) },
+  status: 200,
+});
+
+const routes = (method: Reply, listing: Reply) => (seen: Seen) =>
+  seen.path === '/v1/sys/auth' ? listing : method;
+
+const statusOf = async (error: Promise<unknown>) => {
+  const settled = await error;
+  assert.ok(settled instanceof BaoError);
+  return settled.status;
+};
+
+describe('readAuthMethodData', () => {
+  it('reads a method that exists, without consulting the table', async () => {
+    const reply = { json: { data: { config: {}, type: 'approle' } }, status: 200 };
+    await withFake(routes(reply, table()), async (bao) => {
+      const data = await run({ BAO_ADDR: bao.address }, readAuthMethodData('approle'));
+      assert.equal(data?.['type'], 'approle');
+      assert.deepEqual(
+        bao.seen.map((seen) => seen.path),
+        ['/v1/sys/auth/approle'],
+      );
+    });
+  });
+
+  it("reads a missing method as absent once the table confirms OpenBao's 400", async () => {
+    await withFake(routes(NO_AUTH, table('token/', 'userpass/')), async (bao) => {
+      assert.equal(
+        await run({ BAO_ADDR: bao.address }, readAuthMethodData('approle-new/')),
+        undefined,
+      );
+      assert.deepEqual(
+        bao.seen.map((seen) => seen.path),
+        ['/v1/sys/auth/approle-new', '/v1/sys/auth'],
+      );
+    });
+  });
+
+  it('keeps the 400 when the table lists the method after all', async () => {
+    await withFake(routes(NO_AUTH, table('approle-new/')), async (bao) => {
+      const error = runFailure({ BAO_ADDR: bao.address }, readAuthMethodData('approle-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_AUTH, refused), async (bao) => {
+      const error = runFailure({ BAO_ADDR: bao.address }, readAuthMethodData('approle-new'));
+      assert.equal(await statusOf(error), 400);
+    });
+  });
+
+  it('fails a refused method 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 }, readAuthMethodData('approle'));
+      assert.equal(await statusOf(error), 403);
+      assert.equal(bao.seen.length, 1);
+    });
+  });
+});
+
+describe('enable, tune, disable', () => {
+  it('sends the endpoints and bodies configure-engines sent', async () => {
+    await withFake(
+      () => ({ status: 204 }),
+      async (bao) => {
+        const env = { BAO_ADDR: bao.address };
+        const props = {
+          description: 'Alchemy and CI machine login',
+          path: 'approle/',
+          type: 'approle',
+        };
+        await run(env, enableAuthMethod(props));
+        await run(env, tuneAuthMethod(props));
+        await run(env, disableAuthMethod('approle'));
+        const calls = bao.seen.map((seen) => [seen.method, seen.path, seen.body]);
+        assert.deepEqual(calls, [
+          [
+            'POST',
+            '/v1/sys/auth/approle',
+            JSON.stringify({ type: 'approle', description: 'Alchemy and CI machine login' }),
+          ],
+          [
+            'POST',
+            '/v1/sys/auth/approle/tune',
+            JSON.stringify({ description: 'Alchemy and CI machine login' }),
+          ],
+          ['DELETE', '/v1/sys/auth/approle', ''],
+        ]);
+      },
+    );
+  });
+
+  it('fails a refused enable with OpenBao errors', async () => {
+    await withFake(
+      () => ({ json: { errors: ['path is already in use at approle/'] }, status: 400 }),
+      async (bao) => {
+        const error = runFailure(
+          { BAO_ADDR: bao.address },
+          enableAuthMethod({ path: 'approle', type: 'approle' }),
+        );
+        assert.equal(await statusOf(error), 400);
+      },
+    );
+  });
+});

package/src/openbao/auth-method-wire.ts

@@ -0,0 +1,66 @@
+/**
+ * The OpenBao calls Bao.AuthMethod makes — read one method, enable, tune, disable.
+ *
+ * ★ ENDPOINTS, READ FROM openbao v2.6.2 api/sys_auth.go — the client configure-engines
+ *   used via curl:
+ *     read     GET    sys/auth/<path>
+ *     enable   POST   sys/auth/<path>        — `bao auth enable`
+ *     tune     POST   sys/auth/<path>/tune   — `bao auth tune`
+ *     disable  DELETE sys/auth/<path>        — `bao auth disable`
+ *     table    GET    sys/auth
+ */
+import * as Effect from 'effect/Effect';
+import {
+  type BaoAuthMethodProps,
+  authPath,
+  enableBody,
+  readPath,
+  tuneBody,
+  tunePath,
+} from './auth-method-form.ts';
+import { baoDelete, baoRead, baoWrite } from './bao-http.ts';
+import { BaoError } from './bao-status.ts';
+
+/**
+ * Confirm a method is absent from the auth table, or give back the error that asked.
+ *
+ * ⛔ A MISSING AUTH METHOD IS NOT A 404, IT IS A 400 — THE SAME TRAP AS SECRETS MOUNTS
+ *   (mount-wire.ts). `handleReadAuth` answers an empty path with a bare error; the CLI
+ *   therefore failed and never reached `auth enable`. REASONED FROM THE MOUNT ANALOG
+ *   AND PINNED AGAINST A FAKE — a live missing-method read was not measured.
+ * ★ SO A 400 IS SETTLED BY GET sys/auth. Only a 200 table WITHOUT the `${path}/` key
+ *   is absence. A listed method, a refused listing, or a 404 listing leaves the 400.
+ */
+const absentFromTable = (path: string, asked: BaoError) =>
+  baoRead('sys/auth').pipe(
+    Effect.mapError(
+      (listing) =>
+        new BaoError(asked.status, asked.method, asked.path, [
+          ...asked.errors,
+          `sys/auth could not confirm the method is absent: ${listing.message}`,
+        ]),
+    ),
+    Effect.flatMap((table) =>
+      table !== undefined && !Object.hasOwn(table, `${authPath(path)}/`)
+        ? Effect.succeed(undefined)
+        : Effect.fail(asked),
+    ),
+  );
+
+/** One method's config (`type`, `description`, `config.*_lease_ttl`), or undefined when absent. */
+export const readAuthMethodData = (path: string) =>
+  baoRead(readPath(path)).pipe(
+    Effect.catchIf(
+      (error) => error.status === 400,
+      (error) => absentFromTable(path, error),
+    ),
+  );
+
+export const enableAuthMethod = (props: BaoAuthMethodProps) =>
+  baoWrite('POST', readPath(props.path), enableBody(props));
+
+export const tuneAuthMethod = (props: BaoAuthMethodProps) =>
+  baoWrite('POST', tunePath(props.path), tuneBody(props));
+
+/** ⚠️ THERE IS NO FORCE. Disable is a plain DELETE, same as `bao auth disable`. */
+export const disableAuthMethod = (path: string) => baoDelete(readPath(path));

package/src/openbao/auth-method.ts

@@ -0,0 +1,119 @@
+/**
+ * An OpenBao auth method — path, type, description and lease TTLs.
+ *
+ * ⛔ NO SECRET IN PROPS OR ATTRIBUTES — see policy.ts. This enables `approle` (or jwt/oidc)
+ *   as a mount. Role ids, OIDC client secrets, and secret_ids are out of scope.
+ *
+ * ★ `defaultRemovalPolicy: 'retain'` — disabling a method destroys every role under it
+ *   and revokes tokens minted through those roles. Opt in with
+ *   `.pipe(RemovalPolicy.destroy())`.
+ */
+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 BaoAuthMethodAttributes,
+  type BaoAuthMethodProps,
+  attributesOf,
+  authPath,
+  matches,
+  wantsTune,
+} from './auth-method-form.ts';
+import {
+  disableAuthMethod,
+  enableAuthMethod,
+  readAuthMethodData,
+  tuneAuthMethod,
+} from './auth-method-wire.ts';
+
+export type { BaoAuthMethodAttributes, BaoAuthMethodProps };
+
+export interface BaoAuthMethod extends Resource<
+  'Bao.AuthMethod',
+  BaoAuthMethodProps,
+  BaoAuthMethodAttributes,
+  never,
+  HttpClient.HttpClient
+> {}
+
+export const BaoAuthMethod = Resource<BaoAuthMethod>('Bao.AuthMethod', {
+  defaultRemovalPolicy: 'retain',
+});
+
+const readMethod = (props: BaoAuthMethodProps) =>
+  Effect.gen(function* () {
+    const live = yield* readAuthMethodData(props.path);
+    if (live === undefined) return undefined;
+    return attributesOf(props, live);
+  });
+
+export const BaoAuthMethodProvider = () =>
+  Provider.effect(
+    BaoAuthMethod,
+    Effect.succeed(
+      BaoAuthMethod.Provider.of({
+        /**
+         * ⛔ `bao auth list` IS NOT A LIST OF THINGS THIS OWNS. `token/` is always
+         *   present. Returning it would invite Alchemy to adopt — and then disable —
+         *   methods it never created.
+         */
+        list: () => Effect.succeed([]),
+
+        read: Effect.fn(function* ({ olds }) {
+          return yield* readMethod(olds);
+        }),
+
+        diff: Effect.fn(function* ({ news, output }) {
+          if (output === undefined || !isResolved(news)) return undefined;
+          const live = yield* readMethod(news);
+          if (live === undefined) return { action: 'update' } as const;
+          /**
+           * ⛔ A CHANGED `type` IS A REPLACE. Delete is an auth disable — every role
+           *   under the method dies. `retain` guards both orphan-delete and replace
+           *   (same Alchemy Apply.ts path Bao.Mount documents).
+           */
+          if (live.type !== news.type) return { action: 'replace' } as const;
+          if (matches(live, news)) return { action: 'noop' } as const;
+          return { action: 'update' } as const;
+        }),
+
+        reconcile: Effect.fn(function* ({ news }) {
+          let live = yield* readMethod(news);
+          if (live === undefined) {
+            yield* enableAuthMethod(news);
+            if (wantsTune(news)) yield* tuneAuthMethod(news);
+          } else if (!matches(live, news)) {
+            if (live.type !== news.type) {
+              return yield* Effect.die(
+                new Error(
+                  `Bao.AuthMethod ${authPath(news.path)}: live type ${live.type} != ${news.type}. ` +
+                    'Auth method type is immutable — replace manually.',
+                ),
+              );
+            }
+            yield* tuneAuthMethod(news);
+          }
+          live = yield* readMethod(news);
+          if (live === undefined) {
+            return yield* Effect.die(
+              new Error(
+                `Bao.AuthMethod ${authPath(news.path)}: write returned no error but the method is still absent.`,
+              ),
+            );
+          }
+          return live;
+        }),
+
+        /**
+         * ⛔ DISABLING A METHOD DESTROYS EVERY ROLE UNDER IT. Idempotent as Alchemy
+         *   requires — already gone is success — but retain is the default for a reason.
+         */
+        delete: Effect.fn(function* ({ output }) {
+          yield* disableAuthMethod(output.path);
+          return undefined;
+        }),
+      }),
+    ),
+  );

package/src/openbao/index.ts

@@ -8,6 +8,7 @@
  * ★ 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 { BaoAuthMethod, BaoAuthMethodProvider } from './auth-method.ts';
 export { BaoAuthRole, BaoAuthRoleProvider } from './auth-role.ts';
 export { BaoCloudflareRole, BaoCloudflareRoleProvider } from './cloudflare-role.ts';
 export {

package/src/proxmox/index.test.ts

@@ -0,0 +1,53 @@
+/**
+ * Public barrel: control-plane Resource constructors, not guests or NIC apply.
+ *
+ * ⛔ Lxc/Vm stay Provider-only. A Resource export would let a stack declare
+ *   guests before storage/SDN exist. NodeNetwork/NetworkApply stay off the
+ *   barrel for the same reason — they stage interfaces.new.
+ */
+import { expect, test } from 'bun:test';
+import { PbsDatastore, ProxmoxStorage } from './index.ts';
+
+const src = await Bun.file(new URL('./index.ts', import.meta.url)).text();
+
+const resourceExports = [
+  'PbsDatastore',
+  'PbsPruneJob',
+  'PbsSyncJob',
+  'PbsVerifyJob',
+  'ProxmoxAcl',
+  'ProxmoxBackupJob',
+  'ProxmoxGroup',
+  'ProxmoxHaResource',
+  'ProxmoxHaRule',
+  'ProxmoxMetricServer',
+  'ProxmoxNotificationTarget',
+  'ProxmoxRole',
+  'ProxmoxSdnApply',
+  'ProxmoxSdnSubnet',
+  'ProxmoxSdnVnet',
+  'ProxmoxSdnZone',
+  'ProxmoxStorage',
+  'ProxmoxUser',
+] as const;
+
+test('control-plane Resource constructors are on the public barrel', () => {
+  expect(ProxmoxStorage).toBeDefined();
+  expect(PbsDatastore).toBeDefined();
+  for (const name of resourceExports) {
+    expect(src).toContain(`${name},`);
+  }
+});
+
+test('guests and NIC apply stay Provider-only', () => {
+  expect(src).not.toMatch(/export \{ ProxmoxLxc[, }]/);
+  expect(src).not.toMatch(/export \{ ProxmoxVm[, }]/);
+  expect(src).not.toMatch(/export \{ ProxmoxNodeNetwork[, }]/);
+  expect(src).not.toMatch(/export \{ ProxmoxNetworkApply[, }]/);
+  expect(src).not.toMatch(/export \{ ProxmoxApiToken[, }]/);
+  expect(src).not.toMatch(/export \{ ProxmoxZfsPool[, }]/);
+  expect(src).not.toMatch(/export \{ ProxmoxCephOsd[, }]/);
+  expect(src).not.toMatch(/export \{ ProxmoxCephFs[, }]/);
+  expect(src).not.toMatch(/export \{ ProxmoxCephDaemon[, }]/);
+  expect(src).not.toMatch(/export \{ ProxmoxCephFlag[, }]/);
+});

package/src/proxmox/index.ts

@@ -5,38 +5,44 @@
  *   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.
+ * ★ Control-plane Resource constructors (Storage, SDN, access, HA, backup,
+ *   metrics, PBS) sit next to their Providers. Guests and NIC apply stay
+ *   Provider-only so a stack cannot declare them by accident.
+ * ★ Anything else unlisted is still reachable by path if you genuinely need
+ *   it — that is a deliberate, visible act rather than an accident of barrelling.
  */
-export { ProxmoxAclProvider } from './acl.ts';
+export { ProxmoxAcl, ProxmoxAclProvider } from './acl.ts';
 export { ProxmoxApiTokenProvider } from './api-token.ts';
-export { ProxmoxBackupJobProvider } from './backup-job.ts';
+export { ProxmoxBackupJob, ProxmoxBackupJobProvider } from './backup-job.ts';
 export { ProxmoxCephDaemonProvider } from './ceph-daemon.ts';
 export { ProxmoxCephFlagProvider } from './ceph-flag.ts';
 export { ProxmoxCephFsProvider } from './ceph-fs.ts';
 export { ProxmoxCephOsdProvider } from './ceph-osd.ts';
 export { ProxmoxCephPool, ProxmoxCephPoolProvider } from './ceph-pool.ts';
 export { ProxmoxFirewallAliasProvider } from './firewall-alias.ts';
-export { ProxmoxGroupProvider } from './group.ts';
-export { ProxmoxHaResourceProvider } from './ha-resource.ts';
-export { ProxmoxHaRuleProvider } from './ha-rule.ts';
+export { ProxmoxGroup, ProxmoxGroupProvider } from './group.ts';
+export { ProxmoxHaResource, ProxmoxHaResourceProvider } from './ha-resource.ts';
+export { ProxmoxHaRule, ProxmoxHaRuleProvider } from './ha-rule.ts';
 export { ProxmoxLxcProvider } from './lxc.ts';
-export { ProxmoxMetricServerProvider } from './metric-server.ts';
+export { ProxmoxMetricServer, ProxmoxMetricServerProvider } from './metric-server.ts';
 export { ProxmoxNetworkApplyProvider } from './network-apply.ts';
 export { ProxmoxNodeNetworkProvider } from './node-network.ts';
-export { ProxmoxNotificationTargetProvider } from './notification-target.ts';
-export { PbsDatastoreProvider } from './pbs-datastore.ts';
-export { PbsPruneJobProvider } from './pbs-prune-job.ts';
-export { PbsSyncJobProvider } from './pbs-sync-job.ts';
-export { PbsVerifyJobProvider } from './pbs-verify-job.ts';
+export {
+  ProxmoxNotificationTarget,
+  ProxmoxNotificationTargetProvider,
+} from './notification-target.ts';
+export { PbsDatastore, PbsDatastoreProvider } from './pbs-datastore.ts';
+export { PbsPruneJob, PbsPruneJobProvider } from './pbs-prune-job.ts';
+export { PbsSyncJob, PbsSyncJobProvider } from './pbs-sync-job.ts';
+export { PbsVerifyJob, PbsVerifyJobProvider } from './pbs-verify-job.ts';
 export { ProxmoxPool, ProxmoxPoolProvider } from './pool.ts';
 export { ProxmoxVmProvider } from './qemu.ts';
 export { ProxmoxReplicationJobProvider } from './replication-job.ts';
-export { ProxmoxRoleProvider } from './role.ts';
-export { ProxmoxSdnApplyProvider } from './sdn-apply.ts';
-export { ProxmoxSdnSubnetProvider } from './sdn-subnet.ts';
-export { ProxmoxSdnVnetProvider } from './sdn-vnet.ts';
-export { ProxmoxSdnZoneProvider } from './sdn-zone.ts';
-export { ProxmoxStorageProvider } from './storage.ts';
-export { ProxmoxUserProvider } from './user.ts';
+export { ProxmoxRole, ProxmoxRoleProvider } from './role.ts';
+export { ProxmoxSdnApply, ProxmoxSdnApplyProvider } from './sdn-apply.ts';
+export { ProxmoxSdnSubnet, ProxmoxSdnSubnetProvider } from './sdn-subnet.ts';
+export { ProxmoxSdnVnet, ProxmoxSdnVnetProvider } from './sdn-vnet.ts';
+export { ProxmoxSdnZone, ProxmoxSdnZoneProvider } from './sdn-zone.ts';
+export { ProxmoxStorage, ProxmoxStorageProvider } from './storage.ts';
+export { ProxmoxUser, ProxmoxUserProvider } from './user.ts';
 export { ProxmoxZfsPoolProvider } from './zfs-pool.ts';