@homeflare/alchemy 0.4.1 → 0.6.0

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

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

@@ -0,0 +1,149 @@
+/**
+ * The form half of Bao.KubernetesRole — `auth/<mount>/role/<name>` on a `kubernetes` auth mount:
+ * which service accounts, in which namespaces, may log in, and what their token carries.
+ *
+ * ★ READ FROM openbao v2.6.2 builtin/credential/kubernetes/path_role.go, NOT RECALLED:
+ *   · The write MERGES for names, namespaces, audience and alias source (`GetOk`, :335-392), but
+ *     `bound_service_account_namespace_selector` is `data.Get` — RESET when omitted (:353). Every
+ *     field is therefore sent on every write, defaults included.
+ *   · Names may not be empty, and `*` may not be mixed with other names; namespaces may be empty
+ *     only when a selector is set, with the same `*` rule (:335-372). Refused here first.
+ *   · Roles are stored under the LOWER-CASED name (:396, backend.go:361), so a mixed-case name
+ *     would read back as a different string. Refused, not folded.
+ *   · `audience` is omitted from a read when empty (:206-208); read as `''`.
+ * ⚠️ `aliasNameSource` DECIDES WHO A POD IS. `serviceaccount_uid` (OpenBao's default) names the
+ *   entity alias by the service account's UID; `serviceaccount_name` by `<namespace>/<name>`
+ *   (backend.go:30-34). Changing it on a live role re-names every pod's alias, so their next logins
+ *   land on NEW entities and attribution splits.
+ * ⛔ SO IT IS REQUIRED, NOT DEFAULTED (review 2026-09-21). Every field is sent on every write, so a
+ *   default here would be WRITTEN: adopting a hand-made `serviceaccount_name` role with the prop
+ *   left out would plan a bare `update` and silently re-key every pod onto new entities. The
+ *   machine-access plan chose `serviceaccount_name`; the server's default is the other one — a
+ *   choice this important is made in the declaration, the way Bao.JwtRole's `roleType` is.
+ */
+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 BaoKubernetesAliasSource = 'serviceaccount_name' | 'serviceaccount_uid';
+
+export interface BaoKubernetesRoleProps extends BaoTokenProps {
+  /** Auth mount path. Default `kubernetes`. */
+  mount?: string;
+  /** Role name — lower case, as the server stores it. */
+  name: string;
+  /** Service account names; `['*']` for any. Never empty. */
+  boundServiceAccountNames: readonly string[];
+  /** Namespaces; `['*']` for any. May be empty only with a selector. */
+  boundServiceAccountNamespaces?: readonly string[];
+  /** A label selector (JSON or YAML) for namespaces, ORed with the list. */
+  boundServiceAccountNamespaceSelector?: string;
+  /** The `aud` a service account token must carry. Default none. */
+  audience?: string;
+  /** ⛔ Required — read the ⚠️ and ⛔ above before changing it on a live role. */
+  aliasNameSource: BaoKubernetesAliasSource;
+}
+
+export interface BaoKubernetesRoleCanonical extends BaoTokenForm {
+  aliasNameSource: string;
+  audience: string;
+  boundServiceAccountNames: readonly string[];
+  boundServiceAccountNamespaceSelector: string;
+  boundServiceAccountNamespaces: readonly string[];
+}
+
+/** ⛔ No secret: account names, namespaces, policy names, TTLs. */
+export interface BaoKubernetesRoleAttributes extends BaoKubernetesRoleCanonical {
+  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 canonical = (input: BaoKubernetesRoleCanonical): BaoKubernetesRoleCanonical => ({
+  aliasNameSource: input.aliasNameSource,
+  audience: input.audience,
+  boundServiceAccountNames: sortedSet(input.boundServiceAccountNames),
+  boundServiceAccountNamespaceSelector: input.boundServiceAccountNamespaceSelector.trim(),
+  boundServiceAccountNamespaces: sortedSet(input.boundServiceAccountNamespaces),
+  ...tokenFields(input),
+});
+
+export const canonicalFromProps = (props: BaoKubernetesRoleProps): BaoKubernetesRoleCanonical =>
+  canonical({
+    ...tokenFormOfProps(props),
+    aliasNameSource: props.aliasNameSource,
+    audience: props.audience ?? '',
+    boundServiceAccountNames: props.boundServiceAccountNames,
+    boundServiceAccountNamespaceSelector: props.boundServiceAccountNamespaceSelector ?? '',
+    boundServiceAccountNamespaces: props.boundServiceAccountNamespaces ?? [],
+  });
+
+export const canonicalFromLive = (live: Record<string, unknown>): BaoKubernetesRoleCanonical =>
+  canonical({
+    ...tokenFormOfLive(live),
+    aliasNameSource: text(live['alias_name_source']),
+    audience: text(live['audience']),
+    boundServiceAccountNames: strings(live['bound_service_account_names']),
+    boundServiceAccountNamespaceSelector: text(live['bound_service_account_namespace_selector']),
+    boundServiceAccountNamespaces: strings(live['bound_service_account_namespaces']),
+  });
+
+export const mountOf = (props: { mount?: string }): string =>
+  mountPath(props.mount ?? 'kubernetes');
+
+export const rolePath = (props: { mount?: string; name: string }): string =>
+  `auth/${mountOf(props)}/role/${props.name}`;
+
+export const attributesOf = (
+  props: BaoKubernetesRoleProps,
+  live: Record<string, unknown>,
+): BaoKubernetesRoleAttributes => {
+  const form = canonicalFromLive(live);
+  return { ...form, digest: sha256(JSON.stringify(form)), mount: mountOf(props), name: props.name };
+};
+
+export const matches = (
+  attributes: BaoKubernetesRoleAttributes,
+  props: BaoKubernetesRoleProps,
+): boolean => attributes.digest === sha256(JSON.stringify(canonicalFromProps(props)));
+
+export const writeBody = (props: BaoKubernetesRoleProps): Record<string, unknown> => ({
+  alias_name_source: props.aliasNameSource,
+  audience: props.audience ?? '',
+  bound_service_account_names: [...props.boundServiceAccountNames],
+  bound_service_account_namespace_selector: props.boundServiceAccountNamespaceSelector ?? '',
+  bound_service_account_namespaces: [...(props.boundServiceAccountNamespaces ?? [])],
+  ...tokenBody(props),
+});
+
+const NAME = /^[a-z0-9_](?:[a-z0-9_.-]*[a-z0-9_])?$/;
+
+const starMixed = (values: readonly string[]) => values.length > 1 && values.includes('*');
+
+export const problems = (props: BaoKubernetesRoleProps): readonly string[] => {
+  const found = [...tokenProblems(props)];
+  const namespaces = props.boundServiceAccountNamespaces ?? [];
+  const selector = (props.boundServiceAccountNamespaceSelector ?? '').trim();
+  if (!NAME.test(props.name))
+    found.push(`name \`${props.name}\` must be lower case (stored folded)`);
+  if (props.boundServiceAccountNames.length === 0) found.push('boundServiceAccountNames is empty');
+  if (starMixed(props.boundServiceAccountNames)) found.push('`*` mixed with other account names');
+  if (namespaces.length === 0 && selector === '') {
+    found.push('boundServiceAccountNamespaces is empty and no namespace selector is set');
+  }
+  if (starMixed(namespaces)) found.push('`*` mixed with other namespaces');
+  return found;
+};

package/src/openbao/kubernetes-role.ts

@@ -0,0 +1,94 @@
+/**
+ * A role on a `kubernetes` auth mount — `auth/<mount>/role/<name>`: which service accounts may log
+ * in and what their token carries. METADATA ONLY. The machine-access plan gives k8s pods this
+ * instead of AppRole: one role per namespace/service account.
+ *
+ * ⛔ NO SECRET IN PROPS OR ATTRIBUTES — see policy.ts. The mount's own config (the cluster's CA and
+ *   the token reviewer JWT) is not declared here, and the reviewer JWT must never be.
+ * ⚠️ DELETING A ROLE DOES NOT REVOKE THE TOKENS IT ISSUED — pathRoleDelete removes the storage entry
+ *   and nothing else (path_role.go:239-256).
+ *
+ * ★ REPLACE SEMANTICS (REPLACE.md): `mount` or `name` changed → `replace`, create-first (the new
+ *   path cannot collide). Under the default `retain` the old role stays live until removed by hand.
+ */
+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 BaoKubernetesRoleAttributes,
+  type BaoKubernetesRoleProps,
+  attributesOf,
+  matches,
+  mountOf,
+  problems,
+  rolePath,
+  writeBody,
+} from './kubernetes-role-form.ts';
+import { type RoleSpec, planRole, readRoleAt, reconcileRole } from './role-reconcile.ts';
+
+export type {
+  BaoKubernetesAliasSource,
+  BaoKubernetesRoleAttributes,
+  BaoKubernetesRoleProps,
+} from './kubernetes-role-form.ts';
+
+export interface BaoKubernetesRole extends Resource<
+  'Bao.KubernetesRole',
+  BaoKubernetesRoleProps,
+  BaoKubernetesRoleAttributes,
+  never,
+  HttpClient.HttpClient
+> {}
+
+export const BaoKubernetesRole = Resource<BaoKubernetesRole>('Bao.KubernetesRole', {
+  defaultRemovalPolicy: 'retain',
+});
+
+export const kubernetesRoleSpec = (
+  props: BaoKubernetesRoleProps,
+): RoleSpec<BaoKubernetesRoleAttributes> => ({
+  attributesOf: (live) => attributesOf(props, live),
+  body: writeBody(props),
+  family: 'Bao.KubernetesRole',
+  matches: (attributes) => matches(attributes, props),
+  path: rolePath(props),
+  problems: problems(props),
+});
+
+export const BaoKubernetesRoleProvider = () =>
+  Provider.effect(
+    BaoKubernetesRole,
+    Effect.succeed(
+      BaoKubernetesRole.Provider.of({
+        /** ⛔ The mount's role listing is not a list of things this owns. */
+        list: () => Effect.succeed([]),
+
+        read: Effect.fn(function* ({ olds }) {
+          const found = yield* readRoleAt(kubernetesRoleSpec(olds));
+          return found?.attributes;
+        }),
+
+        /** ⛔ IT COMPARES THE LIVE ROLE, NOT THE STORED DIGEST. */
+        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(kubernetesRoleSpec(news)) } as const;
+        }),
+
+        reconcile: Effect.fn(function* ({ news }) {
+          return yield* reconcileRole(kubernetesRoleSpec(news));
+        }),
+
+        /** Idempotent as Alchemy requires — a missing role deletes as success. */
+        delete: Effect.fn(function* ({ output }) {
+          yield* baoDelete(rolePath(output));
+          return undefined;
+        }),
+      }),
+    ),
+  );