@homeflare/alchemy 0.5.0 → 0.7.0

package/src/openbao/jwt-config.ts

@@ -0,0 +1,85 @@
+/**
+ * `auth/<mount>/config` for a JWT-validating mount — the issuer, keys and algorithms a login token
+ * is checked against. OPTIONAL, NON-SECRET, and deliberately unable to configure an OIDC browser
+ * login: read the ⛔ in jwt-config-form.ts for why `oidc_client_secret` stays out of Alchemy.
+ *
+ * ⚠️ THERE IS NO DELETE. openbao v2.6.2 path_config.go:126-141 defines read and update only; the
+ *   config lives exactly as long as its mount. So `delete` here writes nothing and says so in its
+ *   comment — it cannot be made to "remove" a config, and refusing would wedge every destroy. The
+ *   `retain` default means it only runs when a stack opted into destroy.
+ *
+ * ★ REPLACE SEMANTICS (REPLACE.md): `mount` changed → `replace`: the new mount gets the config;
+ *   the old one keeps its own until that mount is disabled. There is no identity but the mount.
+ */
+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 BaoJwtAuthConfigAttributes,
+  type BaoJwtAuthConfigProps,
+  attributesOf,
+  configPath,
+  matches,
+  mountOf,
+  problems,
+  wouldErase,
+  writeBody,
+} from './jwt-config-form.ts';
+import { type RoleSpec, planRole, readRoleAt, reconcileRole } from './role-reconcile.ts';
+
+export type { BaoJwtAuthConfigAttributes, BaoJwtAuthConfigProps } from './jwt-config-form.ts';
+
+export interface BaoJwtAuthConfig extends Resource<
+  'Bao.JwtAuthConfig',
+  BaoJwtAuthConfigProps,
+  BaoJwtAuthConfigAttributes,
+  never,
+  HttpClient.HttpClient
+> {}
+
+export const BaoJwtAuthConfig = Resource<BaoJwtAuthConfig>('Bao.JwtAuthConfig', {
+  defaultRemovalPolicy: 'retain',
+});
+
+export const jwtConfigSpec = (
+  props: BaoJwtAuthConfigProps,
+): RoleSpec<BaoJwtAuthConfigAttributes> => ({
+  attributesOf: (live) => attributesOf(props, live),
+  body: writeBody(props),
+  family: 'Bao.JwtAuthConfig',
+  matches: (attributes) => matches(attributes, props),
+  path: configPath(props),
+  problems: problems(props),
+  wouldErase,
+});
+
+export const BaoJwtAuthConfigProvider = () =>
+  Provider.effect(
+    BaoJwtAuthConfig,
+    Effect.succeed(
+      BaoJwtAuthConfig.Provider.of({
+        list: () => Effect.succeed([]),
+
+        read: Effect.fn(function* ({ olds }) {
+          const found = yield* readRoleAt(jwtConfigSpec(olds));
+          return found?.attributes;
+        }),
+
+        diff: Effect.fn(function* ({ news, output }) {
+          if (output === undefined || !isResolved(news)) return undefined;
+          if (mountOf(news) !== output.mount) return { action: 'replace' } as const;
+          return { action: yield* planRole(jwtConfigSpec(news)) } as const;
+        }),
+
+        /** ⛔ Refuses, before writing, a live config that carries an OIDC client (wouldErase). */
+        reconcile: Effect.fn(function* ({ news }) {
+          return yield* reconcileRole(jwtConfigSpec(news));
+        }),
+
+        /** ⚠️ Writes nothing — there is no delete endpoint (header). */
+        delete: () => Effect.void,
+      }),
+    ),
+  );

package/src/openbao/jwt-role-form.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Bao.JwtRole's form. Worth pinning: the body carries the four fields the server RESETS when they
+ * are omitted, maps go over as objects, a role read back from OpenBao compares equal to its
+ * declaration, and the server's own refusals are refused here first. Values are placeholders.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  type BaoJwtRoleProps,
+  attributesOf,
+  matches,
+  problems,
+  writeBody,
+} from './jwt-role-form.ts';
+
+const CI: BaoJwtRoleProps = {
+  boundAudiences: ['https://github.com/example-org'],
+  boundClaims: { ref: 'refs/heads/main', repository: ['example-org/app', 'example-org/api'] },
+  boundClaimsType: 'glob',
+  mount: 'jwt-github',
+  name: 'ci-app',
+  roleType: 'jwt',
+  tokenMaxTtl: '30m',
+  tokenPolicies: ['ci-app-deploy'],
+  tokenTtl: '10m',
+  userClaim: 'repository',
+};
+
+/** What OpenBao 2.6.2 answers for CI after the write (path_role.go pathRoleRead + tokenutil). */
+const LIVE: Record<string, unknown> = {
+  allowed_redirect_uris: null,
+  bound_audiences: ['https://github.com/example-org'],
+  bound_claims: { ref: 'refs/heads/main', repository: ['example-org/api', 'example-org/app'] },
+  bound_claims_type: 'glob',
+  bound_subject: '',
+  callback_mode: 'client',
+  claim_mappings: null,
+  clock_skew_leeway: 60,
+  groups_claim: '',
+  oidc_disable_confirmation: false,
+  oidc_scopes: null,
+  role_type: 'jwt',
+  token_bound_cidrs: [],
+  token_explicit_max_ttl: 0,
+  token_max_ttl: 1800,
+  token_no_default_policy: false,
+  token_num_uses: 0,
+  token_period: 0,
+  token_policies: ['ci-app-deploy'],
+  token_ttl: 600,
+  token_type: 'default',
+  user_claim: 'repository',
+  verbose_oidc_logging: false,
+};
+
+const same = (live: Record<string, unknown>, props = CI) =>
+  matches(attributesOf(props, live), props);
+
+describe('jwt role form', () => {
+  it('reads the role OpenBao stored as the role that was declared', () => {
+    assert.equal(same(LIVE), true);
+  });
+
+  it('sends the four fields the server resets when omitted, and maps as objects', () => {
+    const body = writeBody(CI);
+    assert.equal(body['role_type'], 'jwt');
+    assert.equal(body['bound_claims_type'], 'glob');
+    assert.equal(body['callback_mode'], 'client');
+    assert.equal(body['oidc_disable_confirmation'], false);
+    assert.equal(body['verbose_oidc_logging'], false);
+    assert.deepEqual(body['bound_claims'], CI.boundClaims);
+    assert.deepEqual(body['claim_mappings'], {});
+    assert.deepEqual(body['token_policies'], ['ci-app-deploy']);
+  });
+
+  it('sends every token_* field at its default — the write merges, so an omitted one stays stale', () => {
+    const bare: BaoJwtRoleProps = {
+      boundSubject: 'repo:example-org/app:ref:refs/heads/main',
+      name: 'bare',
+      roleType: 'jwt',
+      tokenPolicies: [],
+      userClaim: 'sub',
+    };
+    const token = Object.fromEntries(
+      Object.entries(writeBody(bare)).filter(([key]) => key.startsWith('token_')),
+    );
+    assert.deepEqual(token, {
+      token_bound_cidrs: [],
+      token_explicit_max_ttl: '0',
+      token_max_ttl: '0',
+      token_no_default_policy: false,
+      token_num_uses: 0,
+      token_period: '0',
+      token_policies: [],
+      token_ttl: '0',
+      token_type: 'default',
+    });
+  });
+
+  it('plans update for drift on a managed field, including the two fixed-false ones', () => {
+    const drifted: [string, unknown][] = [
+      ['verbose_oidc_logging', true],
+      ['oidc_disable_confirmation', true],
+      ['role_type', 'oidc'],
+      ['token_policies', ['ci-app-deploy', 'admin']],
+      ['bound_audiences', ['https://github.com/other-org']],
+      ['token_ttl', 3600],
+    ];
+    for (const [field, value] of drifted)
+      assert.equal(same({ ...LIVE, [field]: value }), false, field);
+  });
+
+  it('treats a claim value and a one-element list as the same', () => {
+    const props = {
+      ...CI,
+      boundClaims: { ref: ['refs/heads/main'], repository: CI.boundClaims?.['repository'] ?? [] },
+    };
+    assert.equal(same(LIVE, props), true);
+  });
+
+  it('refuses what the server would refuse, before any call', () => {
+    assert.deepEqual(problems(CI), []);
+    const loose = { ...CI, boundAudiences: [], boundClaims: {} };
+    assert.match(problems(loose).join(), /bound constraint/);
+    assert.match(problems({ ...CI, roleType: 'oidc' }).join(), /allowedRedirectUris/);
+    assert.match(problems({ ...CI, name: 'CI-App' }).join(), /lower case/);
+    assert.match(problems({ ...CI, claimMappings: { email: 'role' } }).join(), /reserved/);
+    assert.match(problems({ ...CI, tokenTtl: '2h' }).join(), /longer than tokenMaxTtl/);
+  });
+});

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

@@ -0,0 +1,231 @@
+/**
+ * The form half of Bao.JwtRole — a role on a `jwt` or `oidc` auth mount (one plugin, two names).
+ *
+ * ★ READ FROM openbao v2.6.2 builtin/credential/jwt/path_role.go, NOT RECALLED:
+ *   · The write MERGES (pathRoleCreateUpdate :494-720): almost every field is `GetOk`, so an
+ *     omitted one keeps its stored value — EXCEPT four that are rebuilt from `data.Get` on every
+ *     write and so RESET when omitted: `role_type` (to `oidc`! :520-526), `bound_claims_type`
+ *     (`string`), `callback_mode` (`client`) and `oidc_disable_confirmation` (false). All four are
+ *     managed here, and every managed field is sent on every write, defaults included, so a value
+ *     set by hand cannot survive behind a green plan.
+ *   · `name` is a lower-case string (:77): `Admins` and `admins` are one role. Refused, not folded.
+ *   · A `jwt` role needs one bound constraint (audiences, subject, claims or token CIDRs) and an
+ *     `oidc` role needs allowed_redirect_uris (:694-709) — refused here with the same rule.
+ *   · `bound_claims` is a TypeMap and `claim_mappings` a TypeKVPairs: sent as JSON OBJECTS. A JSON
+ *     string is refused for a map (the ⛔ on mapValue in ssh-role-form.ts, measured 2026-09-21).
+ * ⛔ `verbose_oidc_logging` AND `oidc_disable_confirmation` ARE ALWAYS SENT FALSE, and a live true
+ *   plans `update`. The first logs received tokens and claims at debug level (:189-194); the second
+ *   removes the confirmation page that guards direct-callback logins against token hijacking
+ *   (RFC 8628 5.4, :205-210). Neither is a prop.
+ * ⚠️ LEFT ALONE (merged, never sent): the three leeways, `oauth2_metadata`, `max_age`,
+ *   `poll_interval`, `user_claim_json_pointer`, `token_policies_template_claims`,
+ *   `token_strictly_bind_ip`. A hand-set value there survives, and is not compared.
+ */
+import {
+  type BaoTokenForm,
+  type BaoTokenProps,
+  tokenBody,
+  tokenFields,
+  tokenFormOfLive,
+  tokenFormOfProps,
+  tokenProblems,
+} from './auth-token-form.ts';
+import { sha256 } from './digest.ts';
+import { mountPath } from './mount-form.ts';
+
+export type BaoJwtRoleType = 'jwt' | 'oidc';
+export type BaoJwtCallbackMode = 'client' | 'device' | 'direct';
+
+export interface BaoJwtRoleProps extends BaoTokenProps {
+  /** Auth mount path, no trailing slash. Default `jwt`; an OIDC mount is often `oidc`. */
+  mount?: string;
+  /** Role name — lower case, as the server stores it. */
+  name: string;
+  /** ⛔ REQUIRED ON PURPOSE: the server's default is `oidc`, even when re-writing a `jwt` role. */
+  roleType: BaoJwtRoleType;
+  /** The claim that names the entity alias, e.g. `sub` or `email`. */
+  userClaim: string;
+  /** `aud` values; any one must match. */
+  boundAudiences?: readonly string[];
+  /** The `sub` a token must carry. */
+  boundSubject?: string;
+  /** How `boundClaims` values match. Default `string`. */
+  boundClaimsType?: 'glob' | 'string';
+  /** Claims that must match, each a value or a list of acceptable values. */
+  boundClaims?: Readonly<Record<string, string | readonly string[]>>;
+  /** Claim → alias metadata key. `role` is reserved, and two claims may not share a key. */
+  claimMappings?: Readonly<Record<string, string>>;
+  /** The claim that names identity group aliases. */
+  groupsClaim?: string;
+  /** OIDC only: the redirect URIs a login may return to. Required for `oidc`. */
+  allowedRedirectUris?: readonly string[];
+  /** OIDC only: scopes to request beyond `openid`. */
+  oidcScopes?: readonly string[];
+  /** OIDC only. Default `client`. */
+  callbackMode?: BaoJwtCallbackMode;
+}
+
+/** Every managed field, normalised. Both sides are built by `canonical`, so key order matches. */
+export interface BaoJwtRoleCanonical extends BaoTokenForm {
+  allowedRedirectUris: readonly string[];
+  boundAudiences: readonly string[];
+  boundClaims: Readonly<Record<string, readonly string[]>>;
+  boundClaimsType: string;
+  boundSubject: string;
+  callbackMode: string;
+  claimMappings: Readonly<Record<string, string>>;
+  groupsClaim: string;
+  oidcDisableConfirmation: boolean;
+  oidcScopes: readonly string[];
+  roleType: string;
+  userClaim: string;
+  verboseOidcLogging: boolean;
+}
+
+/** ⛔ No secret: claim names, audiences, URIs, policy names and TTLs. */
+export interface BaoJwtRoleAttributes extends BaoJwtRoleCanonical {
+  mount: string;
+  name: string;
+  digest: string;
+}
+
+const sortedSet = (values: readonly string[]) => [...new Set(values)].sort();
+const text = (value: unknown) => (typeof value === 'string' ? value : '');
+const strings = (value: unknown): readonly string[] =>
+  Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [];
+const record = (value: unknown): Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+
+/** ⚠️ A claim value and a one-element list match alike (claims.go normalizeList), so both → list. */
+const claimsOf = (value: unknown): Record<string, readonly string[]> => {
+  const source = record(value);
+  const out: Record<string, readonly string[]> = {};
+  for (const key of Object.keys(source).sort()) {
+    const raw = source[key];
+    out[key] = sortedSet(typeof raw === 'string' ? [raw] : strings(raw));
+  }
+  return out;
+};
+
+const mappingsOf = (value: unknown): Record<string, string> => {
+  const source = record(value);
+  const out: Record<string, string> = {};
+  for (const key of Object.keys(source).sort()) out[key] = text(source[key]);
+  return out;
+};
+
+const canonical = (input: BaoJwtRoleCanonical): BaoJwtRoleCanonical => ({
+  allowedRedirectUris: sortedSet(input.allowedRedirectUris),
+  boundAudiences: sortedSet(input.boundAudiences),
+  boundClaims: claimsOf(input.boundClaims),
+  boundClaimsType: input.boundClaimsType,
+  boundSubject: input.boundSubject,
+  callbackMode: input.callbackMode,
+  claimMappings: mappingsOf(input.claimMappings),
+  groupsClaim: input.groupsClaim,
+  oidcDisableConfirmation: input.oidcDisableConfirmation,
+  oidcScopes: sortedSet(input.oidcScopes),
+  roleType: input.roleType,
+  userClaim: input.userClaim,
+  verboseOidcLogging: input.verboseOidcLogging,
+  ...tokenFields(input),
+});
+
+export const canonicalFromProps = (props: BaoJwtRoleProps): BaoJwtRoleCanonical =>
+  canonical({
+    ...tokenFormOfProps(props),
+    allowedRedirectUris: props.allowedRedirectUris ?? [],
+    boundAudiences: props.boundAudiences ?? [],
+    boundClaims: claimsOf(props.boundClaims ?? {}),
+    boundClaimsType: props.boundClaimsType ?? 'string',
+    boundSubject: props.boundSubject ?? '',
+    callbackMode: props.callbackMode ?? 'client',
+    claimMappings: props.claimMappings ?? {},
+    groupsClaim: props.groupsClaim ?? '',
+    oidcDisableConfirmation: false,
+    oidcScopes: props.oidcScopes ?? [],
+    roleType: props.roleType,
+    userClaim: props.userClaim,
+    verboseOidcLogging: false,
+  });
+
+export const canonicalFromLive = (live: Record<string, unknown>): BaoJwtRoleCanonical =>
+  canonical({
+    ...tokenFormOfLive(live),
+    allowedRedirectUris: strings(live['allowed_redirect_uris']),
+    boundAudiences: strings(live['bound_audiences']),
+    boundClaims: claimsOf(live['bound_claims']),
+    boundClaimsType: text(live['bound_claims_type']),
+    boundSubject: text(live['bound_subject']),
+    callbackMode: text(live['callback_mode']),
+    claimMappings: mappingsOf(live['claim_mappings']),
+    groupsClaim: text(live['groups_claim']),
+    oidcDisableConfirmation: live['oidc_disable_confirmation'] === true,
+    oidcScopes: strings(live['oidc_scopes']),
+    roleType: text(live['role_type']),
+    userClaim: text(live['user_claim']),
+    verboseOidcLogging: live['verbose_oidc_logging'] === true,
+  });
+
+export const mountOf = (props: { mount?: string }): string => mountPath(props.mount ?? 'jwt');
+
+export const rolePath = (props: { mount?: string; name: string }): string =>
+  `auth/${mountOf(props)}/role/${props.name}`;
+
+export const attributesOf = (
+  props: BaoJwtRoleProps,
+  live: Record<string, unknown>,
+): BaoJwtRoleAttributes => {
+  const form = canonicalFromLive(live);
+  return { ...form, digest: sha256(JSON.stringify(form)), mount: mountOf(props), name: props.name };
+};
+
+export const matches = (attributes: BaoJwtRoleAttributes, props: BaoJwtRoleProps): boolean =>
+  attributes.digest === sha256(JSON.stringify(canonicalFromProps(props)));
+
+/** The PUT body — every managed field, the two fixed-false ones included (the ⛔ above). */
+export const writeBody = (props: BaoJwtRoleProps): Record<string, unknown> => ({
+  allowed_redirect_uris: [...(props.allowedRedirectUris ?? [])],
+  bound_audiences: [...(props.boundAudiences ?? [])],
+  bound_claims: { ...props.boundClaims },
+  bound_claims_type: props.boundClaimsType ?? 'string',
+  bound_subject: props.boundSubject ?? '',
+  callback_mode: props.callbackMode ?? 'client',
+  claim_mappings: { ...props.claimMappings },
+  groups_claim: props.groupsClaim ?? '',
+  oidc_disable_confirmation: false,
+  oidc_scopes: [...(props.oidcScopes ?? [])],
+  role_type: props.roleType,
+  user_claim: props.userClaim,
+  verbose_oidc_logging: false,
+  ...tokenBody(props),
+});
+
+const NAME = /^[a-z0-9_](?:[a-z0-9_.-]*[a-z0-9_])?$/;
+
+export const problems = (props: BaoJwtRoleProps): readonly string[] => {
+  const found = [...tokenProblems(props)];
+  if (!NAME.test(props.name))
+    found.push(`name \`${props.name}\` must be lower case (the server folds it)`);
+  if (props.userClaim.trim() === '') found.push('userClaim is empty; the server requires one');
+  const bound =
+    (props.boundAudiences?.length ?? 0) > 0 ||
+    (props.boundSubject ?? '') !== '' ||
+    Object.keys(props.boundClaims ?? {}).length > 0 ||
+    (props.tokenBoundCidrs?.length ?? 0) > 0;
+  if (props.roleType === 'jwt' && !bound) {
+    found.push(
+      'a jwt role needs a bound constraint: boundAudiences, boundSubject, boundClaims or tokenBoundCidrs',
+    );
+  }
+  if (props.roleType === 'oidc' && (props.allowedRedirectUris?.length ?? 0) === 0) {
+    found.push('an oidc role needs allowedRedirectUris');
+  }
+  const targets = Object.values(props.claimMappings ?? {});
+  if (targets.includes('role')) found.push('claimMappings may not map to the reserved key `role`');
+  if (new Set(targets).size !== targets.length)
+    found.push('claimMappings maps two claims to one key');
+  return found;
+};

package/src/openbao/jwt-role.ts

@@ -0,0 +1,102 @@
+/**
+ * A role on a `jwt` or `oidc` auth mount — `auth/<mount>/role/<name>`: which tokens may log in,
+ * how the entity is named, and what the resulting OpenBao token carries. METADATA ONLY.
+ *
+ * ⛔ NO SECRET IN PROPS OR ATTRIBUTES — see policy.ts. A role holds claim names, audiences, redirect
+ *   URIs and policy names. The mount's OIDC client secret is config, not role, and stays out of
+ *   Alchemy entirely (the ⛔ in jwt-config.ts).
+ * ⛔ HUMANS GET A NON-ADMIN DEFAULT (machine-access plan, "Admin boundary"): a human role's
+ *   `tokenPolicies` should not include an admin policy, and admin needs login MFA
+ *   (mfa-enforcement.ts). This resource does not know which policy is admin, so it cannot refuse —
+ *   the stack that declares the role owns that line.
+ * ⚠️ DELETING A ROLE DOES NOT REVOKE THE TOKENS IT ISSUED. path_role.go:478 pathRoleDelete removes the
+ *   storage entry and nothing else; those tokens live to their TTL.
+ *
+ * ★ REPLACE SEMANTICS (REPLACE.md): `mount` or `name` changed → `replace`, create-first. The new
+ *   path cannot collide with the old, so no `deleteFirst`. Under the default `retain` the old role
+ *   stays live, and still admits logins, until removed by hand.
+ * ★ `defaultRemovalPolicy: 'retain'`, like every Bao.* family.
+ */
+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 { baoDelete } from './bao-http.ts';
+import {
+  type BaoJwtRoleAttributes,
+  type BaoJwtRoleProps,
+  attributesOf,
+  matches,
+  mountOf,
+  problems,
+  rolePath,
+  writeBody,
+} from './jwt-role-form.ts';
+import { type RoleSpec, planRole, readRoleAt, reconcileRole } from './role-reconcile.ts';
+
+export type {
+  BaoJwtCallbackMode,
+  BaoJwtRoleAttributes,
+  BaoJwtRoleProps,
+  BaoJwtRoleType,
+} from './jwt-role-form.ts';
+
+export interface BaoJwtRole extends Resource<
+  'Bao.JwtRole',
+  BaoJwtRoleProps,
+  BaoJwtRoleAttributes,
+  never,
+  HttpClient.HttpClient
+> {}
+
+export const BaoJwtRole = Resource<BaoJwtRole>('Bao.JwtRole', {
+  defaultRemovalPolicy: 'retain',
+});
+
+export const jwtRoleSpec = (props: BaoJwtRoleProps): RoleSpec<BaoJwtRoleAttributes> => ({
+  attributesOf: (live) => attributesOf(props, live),
+  body: writeBody(props),
+  family: 'Bao.JwtRole',
+  matches: (attributes) => matches(attributes, props),
+  path: rolePath(props),
+  problems: problems(props),
+});
+
+export const BaoJwtRoleProvider = () =>
+  Provider.effect(
+    BaoJwtRole,
+    Effect.succeed(
+      BaoJwtRole.Provider.of({
+        /**
+         * ⛔ `bao list auth/<mount>/role` IS NOT A LIST OF THINGS THIS OWNS — every role answers,
+         *   including the hand-made admin lanes. Returning them invites adopt-then-delete.
+         */
+        list: () => Effect.succeed([]),
+
+        read: Effect.fn(function* ({ olds }) {
+          const found = yield* readRoleAt(jwtRoleSpec(olds));
+          return found?.attributes;
+        }),
+
+        /** ⛔ IT COMPARES THE LIVE ROLE, NOT THE STORED DIGEST — a hand-widened audience is drift. */
+        diff: Effect.fn(function* ({ news, output }) {
+          if (output === undefined || !isResolved(news)) return undefined;
+          if (mountOf(news) !== output.mount || news.name !== output.name) {
+            return { action: 'replace' } as const;
+          }
+          return { action: yield* planRole(jwtRoleSpec(news)) } as const;
+        }),
+
+        reconcile: Effect.fn(function* ({ news }) {
+          return yield* reconcileRole(jwtRoleSpec(news));
+        }),
+
+        /** Idempotent as Alchemy requires — a missing role deletes as success. */
+        delete: Effect.fn(function* ({ output }) {
+          yield* baoDelete(rolePath(output));
+          return undefined;
+        }),
+      }),
+    ),
+  );

package/src/openbao/kubernetes-role-form.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Bao.KubernetesRole's form: the selector the server resets is always sent, a read-back compares
+ * equal, and the server's refusals are refused first. Placeholder names throughout.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  type BaoKubernetesRoleProps,
+  attributesOf,
+  matches,
+  problems,
+  writeBody,
+} from './kubernetes-role-form.ts';
+
+const POD: BaoKubernetesRoleProps = {
+  aliasNameSource: 'serviceaccount_name',
+  boundServiceAccountNames: ['litellm'],
+  boundServiceAccountNamespaces: ['ai'],
+  name: 'ai-litellm',
+  tokenPolicies: ['ai-litellm'],
+  tokenTtl: '1h',
+};
+
+const LIVE: Record<string, unknown> = {
+  alias_name_source: 'serviceaccount_name',
+  bound_service_account_names: ['litellm'],
+  bound_service_account_namespace_selector: '',
+  bound_service_account_namespaces: ['ai'],
+  token_bound_cidrs: [],
+  token_explicit_max_ttl: 0,
+  token_max_ttl: 0,
+  token_no_default_policy: false,
+  token_num_uses: 0,
+  token_period: 0,
+  token_policies: ['ai-litellm'],
+  token_ttl: 3600,
+  token_type: 'default',
+};
+
+const same = (live: Record<string, unknown>, props = POD) =>
+  matches(attributesOf(props, live), props);
+
+describe('kubernetes role form', () => {
+  it('reads the stored role as the declared one; audience absent reads as none', () => {
+    assert.equal(same(LIVE), true);
+  });
+
+  it('plans update when the alias source, names or audience drift', () => {
+    assert.equal(same({ ...LIVE, alias_name_source: 'serviceaccount_uid' }), false);
+    assert.equal(same({ ...LIVE, bound_service_account_names: ['*'] }), false);
+    assert.equal(same({ ...LIVE, audience: 'vault' }), false);
+  });
+
+  it('always sends the selector and audience, so a stale one is cleared', () => {
+    const body = writeBody(POD);
+    assert.equal(body['bound_service_account_namespace_selector'], '');
+    assert.equal(body['audience'], '');
+    assert.equal(body['alias_name_source'], 'serviceaccount_name');
+  });
+
+  it('sends the declared alias source, whichever it is — there is no default to fall back on', () => {
+    const uid = { ...POD, aliasNameSource: 'serviceaccount_uid' as const };
+    assert.equal(writeBody(uid)['alias_name_source'], 'serviceaccount_uid');
+  });
+
+  it('refuses empty names, a mixed `*`, no namespaces, and upper case', () => {
+    assert.deepEqual(problems(POD), []);
+    assert.match(problems({ ...POD, boundServiceAccountNames: [] }).join(), /is empty/);
+    assert.match(problems({ ...POD, boundServiceAccountNames: ['*', 'x'] }).join(), /mixed/);
+    assert.match(
+      problems({ ...POD, boundServiceAccountNamespaces: [] }).join(),
+      /no namespace selector/,
+    );
+    const selected = {
+      ...POD,
+      boundServiceAccountNamespaceSelector: '{"matchLabels":{"a":"b"}}',
+      boundServiceAccountNamespaces: [],
+    };
+    assert.deepEqual(problems(selected), []);
+    assert.match(problems({ ...POD, name: 'AI' }).join(), /lower case/);
+  });
+});