@homeflare/alchemy 0.5.0 → 0.7.0

package/src/openbao/fake-engines.ts

@@ -0,0 +1,119 @@
+/**
+ * Fakes of the three stores behind Bao.Policy, Bao.CloudflareRole and Bao.ProxmoxRole, for fake-bao,
+ * plus Bao.Policy's provider over fake fragment directories. Each store keys its objects the way the
+ * real server does. That is the point: a rename test is only as good as the fake's idea of "the
+ * same object".
+ *
+ * ⛔ TEST-ONLY — see fake-bao.ts. No provider imports this file.
+ */
+import * as Effect from 'effect/Effect';
+import * as FileSystem from 'effect/FileSystem';
+import * as Layer from 'effect/Layer';
+import * as Path from 'effect/Path';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import type { Reply, Seen } from './fake-bao.ts';
+import { parseDuration } from './mount-form.ts';
+import { trimTrailing } from './mount-path.ts';
+import { BaoPolicyProvider } from './policy.ts';
+import { policyKey } from './rename.ts';
+
+type Stored = Record<string, unknown>;
+
+/** An answer for fake-bao that also exposes what it holds, keyed by API path (no `/v1/`). */
+export type Store = ((seen: Seen) => Reply) & { readonly live: Map<string, Stored> };
+
+const ABSENT: Reply = { json: { errors: [] }, status: 404 };
+
+const store = (
+  write: (path: string, body: Record<string, string>, before: Stored | undefined) => Stored,
+  key: (path: string) => string = (path) => path,
+): Store => {
+  const live = new Map<string, Stored>();
+  const answer = (seen: Seen): Reply => {
+    const path = key(seen.path.replace(/^\/v1\//, ''));
+    if (seen.method === 'PUT') {
+      const body = JSON.parse(seen.body) as Record<string, string>;
+      live.set(path, write(path, body, live.get(path)));
+      return { status: 204 };
+    }
+    // ★ A delete answers 204 whether or not the object existed, as all three do.
+    if (seen.method === 'DELETE') {
+      live.delete(path);
+      return { status: 204 };
+    }
+    const data = live.get(path);
+    return data === undefined ? ABSENT : { json: { data }, status: 200 };
+  };
+  return Object.assign(answer, { live });
+};
+
+const lastSegment = (path: string) => path.split('/').at(-1) ?? '';
+
+/**
+ * `sys/policies/acl/<name>`. It strips the policy's trailing newline on write (measured on the live
+ * server — digest.ts), and keys the name as OpenBao does: trimmed and lowercased (`policyKey`).
+ */
+export const aclPolicies = (): Store =>
+  store(
+    (path, body) => ({
+      name: lastSegment(path),
+      policy: trimTrailing(body['policy'] ?? '', '\n'),
+    }),
+    (path) =>
+      path.startsWith('sys/policies/acl/')
+        ? `sys/policies/acl/${policyKey(decodeURIComponent(lastSegment(path)))}`
+        : path,
+  );
+
+/**
+ * `<mount>/roles/<name>` on the Cloudflare engine. A write parses the duration text into seconds and
+ * re-marshals `policies` (path_roles.go:117-146, :199-210). Names are stored verbatim.
+ */
+export const cloudflareRoles = (): Store =>
+  store((path, body) => ({
+    description: body['description'],
+    max_ttl: parseDuration(body['max_ttl'] ?? ''),
+    name: lastSegment(path),
+    // ★ Re-marshalled, as json.Marshal of the stored structs would be.
+    policies: JSON.stringify(JSON.parse(body['policies'] ?? 'null')),
+    ttl: parseDuration(body['ttl'] ?? ''),
+  }));
+
+/**
+ * `<mount>/roles/<name>` on the proxmox engine. A write MERGES into the stored role, and TTLs go over
+ * as seconds (homeflare-openbao-plugins secrets/proxmox/path_roles.go, pathRolesWrite).
+ */
+export const proxmoxRoles = (): Store =>
+  store((path, body, before) => ({
+    max_ttl: 0,
+    name: lastSegment(path),
+    ttl: 0,
+    ...before,
+    ...(body['mint_user'] === undefined ? {} : { mint_user: body['mint_user'] }),
+    ...(body['ttl'] === undefined ? {} : { ttl: Number(body['ttl']) }),
+    ...(body['max_ttl'] === undefined ? {} : { max_ttl: Number(body['max_ttl']) }),
+  }));
+
+/**
+ * Bao.Policy's provider over fragment directories that exist only here: `…/empty` holds no file,
+ * `…/two` holds two, and any other directory one. Each file is one grant named after its own path,
+ * so a directory's content is its name.
+ */
+export const fakePolicyProviders = Layer.mergeAll(
+  BaoPolicyProvider().pipe(
+    Layer.provide(
+      Layer.mergeAll(
+        FileSystem.layerNoop({
+          readDirectory: (dir) =>
+            Effect.succeed(
+              dir.endsWith('/empty') ? [] : dir.endsWith('/two') ? ['a.hcl', 'b.hcl'] : ['a.hcl'],
+            ),
+          readFileString: (path) =>
+            Effect.succeed(`path "${path}" {\n  capabilities = ["read"]\n}`),
+        }),
+        Path.layer,
+      ),
+    ),
+  ),
+  FetchHttpClient.layer,
+);

package/src/openbao/fake-stack.ts

@@ -0,0 +1,112 @@
+/**
+ * Alchemy's own Plan and Apply, run in-process over an in-memory state store, so a test can deploy a
+ * declaration, change it, deploy again, and see what the ENGINE did with a provider's answers: which
+ * action it planned, and which calls reached the fake.
+ *
+ * ★ WHY THE ENGINE AND NOT THE HANDLERS ALONE. A diff that answers `replace` proves nothing by itself.
+ *   What matters is that Apply then creates the new generation, deletes the OLD one with the OLD
+ *   attributes, and keeps it under `retain`. Those are claims about alchemy@2.0.0-beta.79, and this
+ *   harness measures them instead of restating them (REPLACE.md).
+ * ★ NOT alchemy/Test/Bun. Its runtime builds the CLI's profile and credentials stores, which read
+ *   files under the home directory, plus a file logger. This needs none of that: the providers, an
+ *   in-memory state store, a stage, and the stack's own services. It is the composition
+ *   alchemy/src/Deploy.ts uses, minus the platform layer.
+ *
+ * ⛔ TEST-ONLY, AND NEVER A REAL VAULT. `BaoEnv` is provided explicitly, so a BAO_ADDR or BAO_TOKEN
+ *   in the shell running the tests is never read. No provider imports this file.
+ */
+import * as Alchemy from 'alchemy';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import type { BaoEnvironment } from './bao-address.ts';
+import { BaoEnv } from './bao-http.ts';
+import { type Fake, type Reply, type Seen, fakeBao } from './fake-bao.ts';
+
+/** The planned action for each resource, deletions included, keyed by FQN. */
+export type Planned = Readonly<Record<string, string>>;
+
+/** A stack body: resource declarations, as an `alchemy.run.ts` would write them. */
+export type StackBody = Effect.Effect<unknown, unknown, unknown>;
+
+export interface FakeStack {
+  /** Plan, then apply, `body`. Resolves to the plan; rejects with the apply's failure. */
+  readonly deploy: (body: StackBody) => Promise<Planned>;
+}
+
+type Node = { readonly action: string };
+type PlanView = {
+  readonly resources: Readonly<Record<string, Node>>;
+  readonly deletions: Readonly<Record<string, Node | undefined>>;
+};
+
+const actionsOf = (plan: PlanView): Planned => {
+  const out: Record<string, string> = {};
+  for (const [fqn, node] of Object.entries(plan.resources)) out[fqn] = node.action;
+  for (const [fqn, node] of Object.entries(plan.deletions)) {
+    if (node !== undefined) out[fqn] = node.action;
+  }
+  return out;
+};
+
+/**
+ * One stack over one state store, shared by every `deploy`, so the second deploy plans against what
+ * the first one recorded.
+ *
+ * ⚠️ THE CASTS ARE AT THE ENGINE'S TYPED BOUNDARY, NOT IN THE PROVIDERS. `Alchemy.Stack` types its body
+ *   against every service a CLI run provides. Here the body needs only the providers given, and a
+ *   missing one fails the test by name ("Provider not found for …").
+ */
+export const fakeStack = <ROut, E, RIn>(
+  providers: Layer.Layer<ROut, E, RIn>,
+  env: BaoEnvironment,
+  name = 'RenameStack',
+): FakeStack => {
+  const state = Alchemy.inMemoryState();
+  const stack = Alchemy.Stack as unknown as (
+    stackName: string,
+    options: { providers: typeof providers; state: typeof state },
+    body: StackBody,
+  ) => Effect.Effect<{ readonly services: never }, unknown, never>;
+  const plan = Alchemy.Plan.make as unknown as (
+    compiled: unknown,
+  ) => Effect.Effect<PlanView, unknown, never>;
+  const apply = Alchemy.apply as unknown as (planned: PlanView) => Effect.Effect<unknown, unknown>;
+
+  const deploy = (body: StackBody) =>
+    Effect.gen(function* () {
+      const compiled = yield* stack(name, { providers, state }, body);
+      return yield* Effect.gen(function* () {
+        const planned = yield* plan(compiled);
+        yield* apply(planned);
+        return actionsOf(planned);
+      }).pipe(Effect.provide(Layer.succeedContext(compiled.services)));
+    }).pipe(
+      Effect.provideService(Alchemy.Stage, 'test'),
+      Effect.provideService(BaoEnv, env),
+      Effect.provide(state),
+      Effect.scoped,
+    );
+
+  return { deploy: (body) => Effect.runPromise(deploy(body) as Effect.Effect<Planned>) };
+};
+
+/**
+ * A fake engine answering with `answer`, and one stack over it, for one test. The fake stops however
+ * `body` ends.
+ */
+export const withFakeStack = async <ROut, E, RIn>(
+  providers: Layer.Layer<ROut, E, RIn>,
+  answer: (seen: Seen) => Reply,
+  body: (stack: FakeStack, bao: Fake) => Promise<void>,
+): Promise<void> => {
+  const bao = fakeBao(answer);
+  try {
+    await body(fakeStack(providers, { BAO_ADDR: bao.address }), bao);
+  } finally {
+    bao.stop();
+  }
+};
+
+/** Every call that changed something, as `METHOD /v1/path`, in order. */
+export const writesOf = (seen: readonly Seen[]): string[] =>
+  seen.filter((each) => each.method !== 'GET').map((each) => `${each.method} ${each.path}`);

package/src/openbao/host-approles.test.ts

@@ -0,0 +1,121 @@
+/**
+ * hostAppRoles: one role per host, named `<class>--<host>`, and never a secret_id that does not
+ * expire. The hosts and classes here are placeholders, not the estate's.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  HOST_ROLE_SEPARATOR,
+  type HostRoleClass,
+  hostAppRoles,
+  hostRoleName,
+} from './host-approles.ts';
+import { parseDuration } from './mount-form.ts';
+
+const INFRA: HostRoleClass = {
+  policies: ['host-cert', 'pve-node', 'host-cert'],
+  secretIdTtl: '2160h',
+  tokenMaxTtl: '1h',
+  tokenTtl: '15m',
+};
+const SIGNER: HostRoleClass = {
+  policies: ['ssh-signer'],
+  secretIdTtl: '90d',
+  tokenMaxTtl: '30m',
+  tokenTtl: '10m',
+};
+const INPUT = {
+  classes: { 'operator-signer': SIGNER, 'pve-node': INFRA },
+  hosts: [
+    { class: 'pve-node', name: 'node-b' },
+    { class: 'pve-node', name: 'node-a' },
+    { class: 'operator-signer', name: 'workstation-1' },
+  ],
+};
+
+describe('hostAppRoles', () => {
+  it('makes one role per host, named <class>--<host>, sorted', () => {
+    const roles = hostAppRoles(INPUT);
+    assert.deepEqual(
+      roles.map((role) => role.name),
+      ['operator-signer--workstation-1', 'pve-node--node-a', 'pve-node--node-b'],
+    );
+    assert.equal(hostRoleName('pve-node', 'node-a'), 'pve-node--node-a');
+  });
+
+  it('gives every role an expiring secret_id — none has secret_id_ttl 0', () => {
+    for (const role of hostAppRoles(INPUT)) {
+      const seconds = parseDuration(role.secretIdTtl);
+      assert.ok(
+        seconds !== undefined && seconds > 0,
+        `${role.name} secret_id_ttl ${role.secretIdTtl}`,
+      );
+      assert.equal(role.bindSecretId, true);
+    }
+  });
+
+  it("carries the class's policies, de-duplicated, and its TTLs", () => {
+    const role = hostAppRoles(INPUT).find((each) => each.name === 'pve-node--node-a');
+    assert.deepEqual(role?.tokenPolicies, ['host-cert', 'pve-node']);
+    assert.equal(role?.tokenTtl, '15m');
+    assert.equal(role?.secretIdNumUses, 0);
+  });
+
+  it('splits every name back into exactly one class and host', () => {
+    for (const role of hostAppRoles(INPUT)) {
+      assert.equal(role.name.split(HOST_ROLE_SEPARATOR).length, 2, role.name);
+    }
+  });
+
+  it('refuses a secret_id that never expires, or does not parse', () => {
+    for (const secretIdTtl of ['0', '0s', 'forever']) {
+      assert.throws(
+        () =>
+          hostAppRoles({
+            ...INPUT,
+            classes: { ...INPUT.classes, 'pve-node': { ...INFRA, secretIdTtl } },
+          }),
+        /must be a duration above zero/,
+      );
+    }
+  });
+
+  it('refuses unknown classes, duplicate hosts and names that would blur the separator', () => {
+    const bad = [
+      { class: 'nope', name: 'node-c' },
+      { class: 'pve-node', name: 'node-a' },
+      { class: 'pve-node', name: 'node-a' },
+      { class: 'pve-node', name: 'node--x' },
+      { class: 'pve-node', name: 'Node-Y' },
+    ];
+    assert.throws(
+      () => hostAppRoles({ ...INPUT, hosts: bad }),
+      (error: unknown) => {
+        assert.ok(error instanceof Error);
+        assert.match(error.message, /unknown class `nope`/);
+        assert.match(error.message, /`node-a` is listed twice/);
+        assert.match(error.message, /`node--x` is not lowercase/);
+        assert.match(error.message, /`Node-Y` is not lowercase/);
+        return true;
+      },
+    );
+  });
+
+  it('refuses a class with no policies, with root, or with ttl above max', () => {
+    const classes = {
+      empty: { ...INFRA, policies: [] },
+      rooted: { ...INFRA, policies: ['root'] },
+      upside: { ...INFRA, tokenMaxTtl: '5m', tokenTtl: '1h' },
+    };
+    assert.throws(
+      () => hostAppRoles({ classes, hosts: [] }),
+      (error: unknown) => {
+        assert.ok(error instanceof Error);
+        assert.match(error.message, /`empty` has no policies/);
+        assert.match(error.message, /`rooted` grants `root`/);
+        assert.match(error.message, /`upside` tokenTtl is longer/);
+        return true;
+      },
+    );
+  });
+});

package/src/openbao/host-approles.ts

@@ -0,0 +1,126 @@
+/**
+ * One AppRole role per host, generated from a host list and a few class definitions — pure, so a
+ * scaffold test can render every role from one site config and assert on it without a vault.
+ *
+ * ★ WHY PER HOST, NOT PER CLASS. OpenBao sets an AppRole login's entity alias to the role_id, so
+ *   every host sharing a class role is ONE identity: one entity in every audit line, and one cached
+ *   token when two hosts send the same login through a caching proxy (vault consolidation plan,
+ *   decision 8 as amended 2026-09-21; not re-measured here). The CLASS carries the policies and
+ *   TTLs; the ROLE carries the host.
+ *
+ * ★ THE NAMING RULE: `<class>--<host>`, e.g. `pve-node--node-a`.
+ *   · Class and host names are lowercase letters, digits and SINGLE hyphens, so `--` can only ever
+ *     be the separator and a name splits back into exactly one (class, host) pair.
+ *   · Class first, so one class's roles share a prefix a reader (or a policy path glob,
+ *     `auth/approle/role/pve-node--*`) can select — and no hand-made role (`deploy`,
+ *     `approle-rotator`) can match it, because none of them contains `--`.
+ *   · Lowercase because AppRole stores role names lowercased (builtin/credential/approle stores
+ *     `role/<lowercased name>`); a mixed-case name would read back as a different string.
+ *
+ * ⛔ NO ROLE WITHOUT AN EXPIRING SECRET_ID. `secretIdTtl` must parse to MORE than zero: `0` is a
+ *   secret_id that never expires, which is the `deploy` credential the plan is retiring. The plan's
+ *   class default is 90 days (`2160h`, which auth-role-form.test.ts shows OpenBao accepts).
+ * ⛔ `bindSecretId` IS ALWAYS TRUE. A role that logs in on role_id alone makes the role_id — which
+ *   is not treated as a secret — the whole credential.
+ * ⚠️ A RENAMED HOST OR CLASS IS A NEW ROLE: a new role_id, and a new secret_id to push to the host
+ *   in the same change. What Alchemy calls it depends on the logical id. Keyed by the role name (as
+ *   the README does), the old id VANISHES from the stack, so it is an orphan delete, not a
+ *   `replace`. Keyed by something stable, Bao.AuthRole plans a `replace`. Either way the default
+ *   `retain` leaves the old role LIVE, its secret_ids still logging in (alchemy Plan.ts:2040 and
+ *   Apply.ts:2152-2173 honour retain on both paths) — see the ⚠️ in auth-role.ts before renaming.
+ */
+import type { BaoAuthRoleProps } from './auth-role-form.ts';
+import { parseDuration } from './mount-form.ts';
+
+/** What every host of one class gets. */
+export interface HostRoleClass {
+  /** Policy names. ⛔ Never empty, never `root`. */
+  readonly policies: readonly string[];
+  readonly tokenTtl: string;
+  readonly tokenMaxTtl: string;
+  /** ⛔ Must be more than zero — e.g. `2160h` (90 days). */
+  readonly secretIdTtl: string;
+  /** `0` (the default) means unlimited uses, which a host that logs in repeatedly needs. */
+  readonly secretIdNumUses?: number;
+}
+
+export interface HostRoleHost {
+  /** Short host name, e.g. `node-a`. */
+  readonly name: string;
+  /** Key into `classes`. */
+  readonly class: string;
+}
+
+export interface HostAppRolesInput {
+  readonly hosts: readonly HostRoleHost[];
+  readonly classes: Readonly<Record<string, HostRoleClass>>;
+}
+
+/** Lowercase letters and digits, single hyphens between them. */
+const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export const HOST_ROLE_SEPARATOR = '--';
+
+/** The naming rule, in one place: `<class>--<host>`. */
+export const hostRoleName = (className: string, host: string): string =>
+  `${className}${HOST_ROLE_SEPARATOR}${host}`;
+
+const classProblems = (name: string, spec: HostRoleClass): string[] => {
+  const found: string[] = [];
+  if (!NAME.test(name))
+    found.push(`class \`${name}\` is not lowercase letters, digits, single hyphens`);
+  if (spec.policies.length === 0) found.push(`class \`${name}\` has no policies`);
+  if (spec.policies.includes('root')) found.push(`class \`${name}\` grants \`root\``);
+  const secretId = parseDuration(spec.secretIdTtl);
+  if (secretId === undefined || secretId <= 0) {
+    found.push(
+      `class \`${name}\` secretIdTtl \`${spec.secretIdTtl}\` must be a duration above zero ` +
+        '(0 never expires)',
+    );
+  }
+  const ttl = parseDuration(spec.tokenTtl);
+  const max = parseDuration(spec.tokenMaxTtl);
+  if (ttl === undefined || max === undefined) {
+    found.push(`class \`${name}\` token TTLs must be durations like 15m or 1h`);
+  } else if (max > 0 && ttl > max) {
+    found.push(`class \`${name}\` tokenTtl is longer than tokenMaxTtl`);
+  }
+  return found;
+};
+
+/**
+ * Every host's role props, sorted by role name. Throws, naming every problem at once, on a class or
+ * host that breaks a rule above — this runs when a stack is defined, so a throw stops the plan.
+ */
+export const hostAppRoles = (input: HostAppRolesInput): readonly BaoAuthRoleProps[] => {
+  const problems = Object.entries(input.classes).flatMap(([name, spec]) =>
+    classProblems(name, spec),
+  );
+  const seen = new Set<string>();
+  const roles: BaoAuthRoleProps[] = [];
+  for (const host of input.hosts) {
+    if (!NAME.test(host.name)) {
+      problems.push(`host \`${host.name}\` is not lowercase letters, digits, single hyphens`);
+    }
+    if (seen.has(host.name)) problems.push(`host \`${host.name}\` is listed twice`);
+    seen.add(host.name);
+    const spec = input.classes[host.class];
+    if (spec === undefined) {
+      problems.push(`host \`${host.name}\` names unknown class \`${host.class}\``);
+      continue;
+    }
+    roles.push({
+      bindSecretId: true,
+      name: hostRoleName(host.class, host.name),
+      secretIdNumUses: spec.secretIdNumUses ?? 0,
+      secretIdTtl: spec.secretIdTtl,
+      tokenMaxTtl: spec.tokenMaxTtl,
+      tokenPolicies: [...new Set(spec.policies)].sort(),
+      tokenTtl: spec.tokenTtl,
+    });
+  }
+  if (problems.length > 0) {
+    throw new Error(`hostAppRoles refused the input: ${problems.join('; ')}.`);
+  }
+  return roles.sort((a, b) => a.name.localeCompare(b.name));
+};

package/src/openbao/index.ts

@@ -10,6 +10,10 @@
  * ★ THE APPROLE LOGIN IS HERE FOR SCRIPTS, NOT STACKS (approle-login.ts). A wrapper that logs in
  *   and revokes on exit needs it, and giving it the families' own transport is what keeps a script
  *   and a stack from disagreeing about which server BAO_ADDR means.
+ * ★ SO IS THE IDENTITY GUARD (bao-identity.ts), for the opposite reason: a stack calls it FIRST, so
+ *   no family plans against a vault that is not the one the stack was written for.
+ * ★ hostAppRoles IS PURE — no provider, no call — so a scaffold test can render every per-host
+ *   AppRole from one site config.
  */
 export type { AppRoleLogin, AppRoleLoginInput, BaoLoginFailure } from './approle-login.ts';
 export {
@@ -20,7 +24,10 @@ export {
   revokeSelfEffect,
 } from './approle-login.ts';
 export { BaoAuthMethod, BaoAuthMethodProvider } from './auth-method.ts';
+export type { BaoAuthRoleProps } from './auth-role.ts';
 export { BaoAuthRole, BaoAuthRoleProvider } from './auth-role.ts';
+export type { BaoIdentity, BaoIdentityExpected, BaoIdentityFailure } from './bao-identity.ts';
+export { BaoIdentityError, assertBaoIdentity, assertBaoIdentityEffect } from './bao-identity.ts';
 export { BaoCloudflareRole, BaoCloudflareRoleProvider } from './cloudflare-role.ts';
 export {
   CloudflarePermissionGroups,
@@ -31,6 +38,18 @@ export type { CloudflareZone, ExpandedRole } from './cloudflare-roles-expand.ts'
 export { expandAccount, expandAll, mountName } from './cloudflare-roles-expand.ts';
 export type { RolesConfig, SurfaceSpec } from './cloudflare-roles-config.ts';
 export { parseRolesConfig } from './cloudflare-roles-config.ts';
+export type { HostAppRolesInput, HostRoleClass, HostRoleHost } from './host-approles.ts';
+export { HOST_ROLE_SEPARATOR, hostAppRoles, hostRoleName } from './host-approles.ts';
+export type { BaoJwtAuthConfigProps } from './jwt-config.ts';
+export { BaoJwtAuthConfig, BaoJwtAuthConfigProvider } from './jwt-config.ts';
+export type { BaoJwtRoleProps, BaoJwtRoleType } from './jwt-role.ts';
+export { BaoJwtRole, BaoJwtRoleProvider } from './jwt-role.ts';
+export type { BaoKubernetesAliasSource, BaoKubernetesRoleProps } from './kubernetes-role.ts';
+export { BaoKubernetesRole, BaoKubernetesRoleProvider } from './kubernetes-role.ts';
+export type { BaoMfaLoginEnforcementProps } from './mfa-enforcement.ts';
+export { BaoMfaLoginEnforcement, BaoMfaLoginEnforcementProvider } from './mfa-enforcement.ts';
+export type { BaoMfaTotpMethodProps, BaoTotpAlgorithm } from './mfa-totp.ts';
+export { BaoMfaTotpMethod, BaoMfaTotpMethodProvider } from './mfa-totp.ts';
 export { BaoMount, BaoMountProvider } from './mount.ts';
 export { BaoPkiRole, BaoPkiRoleProvider } from './pki-role.ts';
 export type { BaoPluginProps, BaoPluginType } from './plugin.ts';

package/src/openbao/jwt-config-form.ts

@@ -0,0 +1,161 @@
+/**
+ * The form half of Bao.JwtAuthConfig — `auth/<mount>/config` for a mount that VALIDATES JWTs
+ * (GitHub Actions OIDC, a Kubernetes issuer, a JWKS endpoint). NON-SECRET FIELDS ONLY.
+ *
+ * ⛔ `oidc_client_secret` IS NOT A PROP, AND THIS RESOURCE REFUSES TO TOUCH A MOUNT THAT HAS ONE.
+ *   Three reasons, each sufficient:
+ *   1. Alchemy stores props and attributes UNENCRYPTED in its state store (policy.ts), which is
+ *      dumped nightly to another host. A client secret there outlives the vault that guards it.
+ *   2. The read never returns it (path_config.go:266-315 lists every field it answers; the secret
+ *      is not one, and it is `Sensitive`, :62-68), so a diff could never see it drift.
+ *   3. THE WRITE IS A FULL REPLACE. pathConfigWrite (:321-345) builds the whole config from
+ *      `d.Get`, so a write that leaves the secret out ERASES it — and with `oidc_client_id` still
+ *      set the server refuses, while with both gone (:382-386) every OIDC browser login breaks.
+ *   So a mount whose live config carries `oidc_client_id` is refused by `wouldErase`: configure
+ *   an OIDC login mount by hand, or by a tool that reads the secret from KV at apply time.
+ * ⚠️ THE WRITE CALLS OUT. With a discovery URL or JWKS URL the SERVER fetches it during the write
+ *   (:387-420) and refuses on failure ("error checking oidc discovery URL"): the vault must reach
+ *   the issuer, not only the machine running the plan.
+ */
+import { sha256 } from './digest.ts';
+import { mountPath } from './mount-form.ts';
+
+export interface BaoJwtAuthConfigProps {
+  /** Auth mount path. Default `jwt`. */
+  mount?: string;
+  /** Issuer base URL, WITHOUT `/.well-known/openid-configuration` (the server refuses that). */
+  oidcDiscoveryUrl?: string;
+  /** PEM CA for the discovery URL, when its certificate is not publicly trusted. */
+  oidcDiscoveryCaPem?: string;
+  /** A JWKS URL, instead of discovery. */
+  jwksUrl?: string;
+  /** PEM CA for the JWKS URL. */
+  jwksCaPem?: string;
+  /** PEM PUBLIC keys, instead of either URL. */
+  jwtValidationPubkeys?: readonly string[];
+  /** Algorithms accepted. Default none — which the server reads as RS256. */
+  jwtSupportedAlgs?: readonly string[];
+  /** The `iss` a token must carry. */
+  boundIssuer?: string;
+  /** Role used when a login names none. Lower case. */
+  defaultRole?: string;
+}
+
+export interface BaoJwtAuthConfigCanonical {
+  boundIssuer: string;
+  defaultRole: string;
+  jwksCaPem: string;
+  jwksUrl: string;
+  jwtSupportedAlgs: readonly string[];
+  jwtValidationPubkeys: readonly string[];
+  oidcDiscoveryCaPem: string;
+  oidcDiscoveryUrl: string;
+}
+
+/** ⛔ No secret — URLs, public keys, CA certificates, names. */
+export interface BaoJwtAuthConfigAttributes extends BaoJwtAuthConfigCanonical {
+  mount: string;
+  digest: string;
+}
+
+const text = (value: unknown) => (typeof value === 'string' ? value.trim() : '');
+const strings = (value: unknown): readonly string[] =>
+  Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [];
+const sortedSet = (values: readonly string[]) =>
+  [...new Set(values.map((value) => value.trim()))].sort();
+
+const canonical = (input: BaoJwtAuthConfigCanonical): BaoJwtAuthConfigCanonical => ({
+  boundIssuer: input.boundIssuer.trim(),
+  defaultRole: input.defaultRole.trim(),
+  jwksCaPem: input.jwksCaPem.trim(),
+  jwksUrl: input.jwksUrl.trim(),
+  jwtSupportedAlgs: sortedSet(input.jwtSupportedAlgs),
+  jwtValidationPubkeys: sortedSet(input.jwtValidationPubkeys),
+  oidcDiscoveryCaPem: input.oidcDiscoveryCaPem.trim(),
+  oidcDiscoveryUrl: input.oidcDiscoveryUrl.trim(),
+});
+
+export const canonicalFromProps = (props: BaoJwtAuthConfigProps): BaoJwtAuthConfigCanonical =>
+  canonical({
+    boundIssuer: props.boundIssuer ?? '',
+    defaultRole: props.defaultRole ?? '',
+    jwksCaPem: props.jwksCaPem ?? '',
+    jwksUrl: props.jwksUrl ?? '',
+    jwtSupportedAlgs: props.jwtSupportedAlgs ?? [],
+    jwtValidationPubkeys: props.jwtValidationPubkeys ?? [],
+    oidcDiscoveryCaPem: props.oidcDiscoveryCaPem ?? '',
+    oidcDiscoveryUrl: props.oidcDiscoveryUrl ?? '',
+  });
+
+export const canonicalFromLive = (live: Record<string, unknown>): BaoJwtAuthConfigCanonical =>
+  canonical({
+    boundIssuer: text(live['bound_issuer']),
+    defaultRole: text(live['default_role']),
+    jwksCaPem: text(live['jwks_ca_pem']),
+    jwksUrl: text(live['jwks_url']),
+    jwtSupportedAlgs: strings(live['jwt_supported_algs']),
+    jwtValidationPubkeys: strings(live['jwt_validation_pubkeys']),
+    oidcDiscoveryCaPem: text(live['oidc_discovery_ca_pem']),
+    oidcDiscoveryUrl: text(live['oidc_discovery_url']),
+  });
+
+export const mountOf = (props: { mount?: string }): string => mountPath(props.mount ?? 'jwt');
+
+export const configPath = (props: { mount?: string }): string => `auth/${mountOf(props)}/config`;
+
+export const attributesOf = (
+  props: BaoJwtAuthConfigProps,
+  live: Record<string, unknown>,
+): BaoJwtAuthConfigAttributes => {
+  const form = canonicalFromLive(live);
+  return { ...form, digest: sha256(JSON.stringify(form)), mount: mountOf(props) };
+};
+
+export const matches = (attributes: BaoJwtAuthConfigAttributes, props: BaoJwtAuthConfigProps) =>
+  attributes.digest === sha256(JSON.stringify(canonicalFromProps(props)));
+
+/** Every non-secret field — the write is a full replace, so what is left out is reset. */
+export const writeBody = (props: BaoJwtAuthConfigProps): Record<string, unknown> => ({
+  bound_issuer: props.boundIssuer ?? '',
+  default_role: props.defaultRole ?? '',
+  jwks_ca_pem: props.jwksCaPem ?? '',
+  jwks_url: props.jwksUrl ?? '',
+  jwt_supported_algs: [...(props.jwtSupportedAlgs ?? [])],
+  jwt_validation_pubkeys: [...(props.jwtValidationPubkeys ?? [])],
+  oidc_discovery_ca_pem: props.oidcDiscoveryCaPem ?? '',
+  oidc_discovery_url: props.oidcDiscoveryUrl ?? '',
+});
+
+/** Live fields the full-replace write would reset, which this resource deliberately does not model. */
+export const wouldErase = (live: Record<string, unknown>): readonly string[] => {
+  const lost: string[] = [];
+  if (text(live['oidc_client_id']) !== '') lost.push('oidc_client_id (and its unreadable secret)');
+  const provider = live['provider_config'];
+  if (typeof provider === 'object' && provider !== null && Object.keys(provider).length > 0) {
+    lost.push('provider_config');
+  }
+  if (text(live['oidc_response_mode']) !== '') lost.push('oidc_response_mode');
+  if (strings(live['oidc_response_types']).length > 0) lost.push('oidc_response_types');
+  if (strings(live['override_allowed_server_names']).length > 0) {
+    lost.push('override_allowed_server_names');
+  }
+  return lost;
+};
+
+export const problems = (props: BaoJwtAuthConfigProps): readonly string[] => {
+  const found: string[] = [];
+  const sources = [
+    (props.oidcDiscoveryUrl ?? '') !== '',
+    (props.jwksUrl ?? '') !== '',
+    (props.jwtValidationPubkeys?.length ?? 0) > 0,
+  ].filter(Boolean).length;
+  if (sources !== 1) {
+    found.push('exactly one of oidcDiscoveryUrl, jwksUrl or jwtValidationPubkeys must be set');
+  }
+  if ((props.oidcDiscoveryUrl ?? '').includes('.well-known')) {
+    found.push('oidcDiscoveryUrl must be the issuer, without /.well-known/openid-configuration');
+  }
+  const role = props.defaultRole ?? '';
+  if (role !== role.toLowerCase()) found.push(`defaultRole \`${role}\` must be lower case`);
+  return found;
+};