@homeflare/alchemy 0.5.0 → 0.6.0

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;
+};

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/);
+  });
+});