@homeflare/alchemy 0.3.1 → 0.4.0

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

@@ -0,0 +1,62 @@
+/**
+ * Auth-method shape: path, type, optional description/TTLs. No secrets.
+ * The write bodies are what configure-engines POSTed for approle.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  type BaoAuthMethodProps,
+  attributesOf,
+  authPath,
+  enableBody,
+  matches,
+  readPath,
+  tuneBody,
+  tunePath,
+  wantsTune,
+} from './auth-method-form.ts';
+
+const PROPS: BaoAuthMethodProps = {
+  description: 'Alchemy and CI machine login',
+  path: 'approle/',
+  type: 'approle',
+};
+
+describe('auth-method form', () => {
+  it('strips a trailing slash the way sys/auth keys are stored', () => {
+    assert.equal(authPath('approle/'), 'approle');
+    assert.equal(readPath('approle/'), 'sys/auth/approle');
+    assert.equal(tunePath('approle'), 'sys/auth/approle/tune');
+  });
+
+  it('enables with type and description, the body configure-engines sent', () => {
+    assert.deepEqual(enableBody(PROPS), {
+      description: 'Alchemy and CI machine login',
+      type: 'approle',
+    });
+    assert.deepEqual(enableBody({ path: 'approle', type: 'approle' }), { type: 'approle' });
+  });
+
+  it('tunes only named fields', () => {
+    assert.deepEqual(tuneBody(PROPS), { description: 'Alchemy and CI machine login' });
+    assert.deepEqual(tuneBody({ defaultLeaseTtl: '768h', path: 'approle', type: 'approle' }), {
+      default_lease_ttl: '768h',
+    });
+    assert.equal(wantsTune({ path: 'approle', type: 'approle' }), false);
+    assert.equal(wantsTune(PROPS), true);
+  });
+
+  it('reads live listing fields into attributes and matches the declaration', () => {
+    const live = {
+      config: { default_lease_ttl: 0, max_lease_ttl: 0 },
+      description: 'Alchemy and CI machine login',
+      type: 'approle',
+    };
+    const attrs = attributesOf(PROPS, live);
+    assert.equal(attrs.path, 'approle');
+    assert.equal(attrs.type, 'approle');
+    assert.equal(attrs.description, 'Alchemy and CI machine login');
+    assert.equal(matches(attrs, PROPS), true);
+    assert.equal(matches(attrs, { ...PROPS, type: 'userpass' }), false);
+  });
+});

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

@@ -0,0 +1,112 @@
+/**
+ * Auth-method shape — path, type, description, lease TTLs. METADATA ONLY.
+ *
+ * ⛔ NO SECRET IN PROPS. Enabling `approle` (or jwt/oidc) is a mount, not a credential.
+ *   Role ids, OIDC client secrets, and secret_ids stay out of Alchemy state.
+ */
+import { sha256 } from './digest.ts';
+import { mountPath, ttlSeconds } from './mount-form.ts';
+
+export interface BaoAuthMethodProps {
+  /** Auth path without trailing slash, as `sys/auth/<path>` takes it. */
+  path: string;
+  /** Auth method type, e.g. `approle`, `jwt`, `oidc`. */
+  type: string;
+  /** Human description — sent on enable and on tune, as configure-engines does. */
+  description?: string;
+  /** Default lease TTL, e.g. `768h`. */
+  defaultLeaseTtl?: string;
+  /** Max lease TTL, e.g. `8760h`. */
+  maxLeaseTtl?: string;
+}
+
+export interface BaoAuthMethodAttributes {
+  path: string;
+  type: string;
+  description: string;
+  defaultLeaseTtl: string;
+  maxLeaseTtl: string;
+  /** SHA-256 of the managed fields — safe to persist; see policy.ts. */
+  digest: string;
+}
+
+/** Auth path without a trailing slash — listing keys are `${path}/`. */
+export const authPath = (path: string) => mountPath(path);
+
+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: BaoAuthMethodProps,
+  live: Record<string, unknown>,
+): BaoAuthMethodAttributes => {
+  const config = configOf(live);
+  const attrs = {
+    path: authPath(props.path),
+    type: text(live['type']) || props.type,
+    description: text(live['description']),
+    defaultLeaseTtl: ttlProp(ttlSeconds(config['default_lease_ttl'])),
+    maxLeaseTtl: ttlProp(ttlSeconds(config['max_lease_ttl'])),
+  };
+  return { ...attrs, digest: sha256(JSON.stringify(attrs)) };
+};
+
+/** `sys/auth/<path>` — read, enable and disable all address the method here. */
+export const readPath = (path: string) => `sys/auth/${authPath(path)}`;
+
+/**
+ * ★ SAME TUNE ROUTE SHAPE AS SECRETS MOUNTS. `bao auth tune` hits
+ *   `sys/auth/<path>/tune` (openbao v2.6.2 api/sys_auth.go TuneAuth).
+ */
+export const tunePath = (path: string) => `${readPath(path)}/tune`;
+
+/**
+ * The enable body. configure-engines POSTed `{ type, description }` for approle.
+ *
+ * ⚠️ TTLs ARE NOT SENT HERE. reconcile tunes them after enable, same as Bao.Mount.
+ */
+export const enableBody = (props: BaoAuthMethodProps): Record<string, string> => {
+  const body: Record<string, string> = { type: props.type };
+  if (props.description !== undefined) body['description'] = props.description;
+  return body;
+};
+
+/** Tune body — only the fields the declaration names. An omitted field is left alone. */
+export const tuneBody = (props: BaoAuthMethodProps): 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: BaoAuthMethodAttributes, props: BaoAuthMethodProps) =>
+  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: BaoAuthMethodProps) =>
+  props.description !== undefined ||
+  props.defaultLeaseTtl !== undefined ||
+  props.maxLeaseTtl !== undefined;

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 {