@homeflare/alchemy 0.5.0 → 0.6.0

package/src/openbao/mount.ts

@@ -7,21 +7,25 @@
  *
  * ★ `defaultRemovalPolicy: 'retain'` — disabling a mount destroys every secret under it.
  *   Opt in with `.pipe(RemovalPolicy.destroy())`; see resource.ts in house/proxmox.
+ *
+ * ★ REPLACE SEMANTICS (audited 2026-09-21, see src/openbao/REPLACE.md):
+ *   · `type` changed → plans `replace`, and the APPLY FAILS, destroying nothing: the new
+ *     generation's path is the old one's, still occupied, so its reconcile dies "type is
+ *     immutable" before any write (mount-reconcile.ts). Change a type by hand. ⛔ Not `deleteFirst`
+ *     on purpose — under `destroy` that would disable the mount, every secret with it, on a typo.
+ *   · `path` changed → FAILS the plan unless `remountFrom` names the old path, which is an
+ *     in-place `update` that moves the mount and its data (mount-move.ts). It used to be an
+ *     `update` that enabled an EMPTY mount at the new path.
  */
 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 BaoMountAttributes,
-  type BaoMountProps,
-  attributesOf,
-  matches,
-  mountPath,
-  wantsTune,
-} from './mount-form.ts';
-import { disableMount, enableMount, readMountData, tuneMount } from './mount-wire.ts';
+import { type BaoMountAttributes, type BaoMountProps, matches } from './mount-form.ts';
+import { planMove } from './mount-move.ts';
+import { readMount, reconcileMount } from './mount-reconcile.ts';
+import { disableMount } from './mount-wire.ts';
 
 export type { BaoMountAttributes, BaoMountProps };
 
@@ -37,13 +41,6 @@ export const BaoMount = Resource<BaoMount>('Bao.Mount', {
   defaultRemovalPolicy: 'retain',
 });
 
-const readMount = (props: BaoMountProps) =>
-  Effect.gen(function* () {
-    const live = yield* readMountData(props.path);
-    if (live === undefined) return undefined;
-    return attributesOf(props, live);
-  });
-
 export const BaoMountProvider = () =>
   Provider.effect(
     BaoMount,
@@ -64,6 +61,13 @@ export const BaoMountProvider = () =>
 
         diff: Effect.fn(function* ({ news, output }) {
           if (output === undefined || !isResolved(news)) return undefined;
+          /**
+           * ⛔ A CHANGED PATH IS DECIDED HERE, BEFORE ANY READ OF THE NEW PATH — reading it would
+           *   find nothing and plan `update`, which is how an empty mount used to get enabled.
+           */
+          const move = planMove('Bao.Mount', output.path, news.path, news.remountFrom);
+          if (move.kind === 'refuse') return yield* Effect.die(new Error(move.message));
+          if (move.kind === 'move') return { action: 'update' } as const;
           const live = yield* readMount(news);
           if (live === undefined) return { action: 'update' } as const;
           /**
@@ -77,8 +81,9 @@ export const BaoMountProvider = () =>
            *   it is true the engine logs "Retaining replaced resource (removal policy: retain)"
            *   and skips the delete entirely. Every mount this package declares carries the retain
            *   default (see the ★ on the resource below), so a wrong `type` string cannot disable a
-           *   live mount. What it CAN do is try to enable a second mount at an occupied path,
-           *   which OpenBao refuses loudly — a failed deploy, not a lost shelf.
+           *   live mount. What it CAN do is fail: the new generation reads the SAME path, finds the
+           *   old type there and dies before any write (mount-reconcile.ts) — a failed deploy, not a
+           *   lost shelf (corrected 2026-09-21; this said OpenBao refused a second enable).
            * ⚠️ THAT SAFETY IS THE DECORATION'S, NOT THIS LINE'S. A caller who opts into
            *   `.pipe(RemovalPolicy.destroy())` gets the destructive replace, which is the correct
            *   meaning of opting in and is worth knowing before you type it on a mount.
@@ -91,32 +96,10 @@ export const BaoMountProvider = () =>
         /**
          * ★ A REFUSED ENABLE OR TUNE FAILS THE EFFECT WITH OpenBao's OWN `errors`, naming the
          *   method and path — the job the per-command exit-code checks used to do by hand.
+         *   The body, and the move, live in mount-reconcile.ts.
          */
-        reconcile: Effect.fn(function* ({ news }) {
-          let live = yield* readMount(news);
-          if (live === undefined) {
-            yield* enableMount(news);
-            if (wantsTune(news)) yield* tuneMount(news);
-          } else if (!matches(live, news)) {
-            if (live.type !== news.type) {
-              return yield* Effect.die(
-                new Error(
-                  `Bao.Mount ${mountPath(news.path)}: live type ${live.type} != ${news.type}. ` +
-                    'Secrets engine type is immutable — replace manually.',
-                ),
-              );
-            }
-            yield* tuneMount(news);
-          }
-          live = yield* readMount(news);
-          if (live === undefined) {
-            return yield* Effect.die(
-              new Error(
-                `Bao.Mount ${mountPath(news.path)}: write returned no error but the mount is still absent.`,
-              ),
-            );
-          }
-          return live;
+        reconcile: Effect.fn(function* ({ news, output }) {
+          return yield* reconcileMount(news, output?.path);
         }),
 
         /**

package/src/openbao/pki-role-canonical.ts

@@ -0,0 +1,163 @@
+/**
+ * Bao.PkiRole's canonical form — the managed field set, normalised so both sides of a diff are
+ * byte-comparable. Split from pki-role-form.ts for the 250-line cap when six fields were added
+ * (2026-09-21); the reasoning below moved with the code, unchanged.
+ *
+ * ★ THE SIX FIELDS ADDED 2026-09-21 — require_cn, enforce_hostnames, key_usage,
+ *   allowed_domains_template, no_store, generate_lease — WERE ALREADY BEING WRITTEN, just never
+ *   declared. The role write is a full replace (pki-role.ts), and openbao v2.6.2
+ *   builtin/logical/pki/path_roles.go pathRoleCreate (:1153-1196) builds each of them from
+ *   `data.Get`, i.e. its schema default when the request omits it. So every write this resource
+ *   ever made reset them — a hand-set `no_store` or a narrowed `key_usage` vanished behind a
+ *   green plan. Their defaults below are OpenBao's own (schema :560-575, :690-720, :800-845), so a
+ *   role this resource wrote reads back unchanged and plans `noop`.
+ */
+import { sha256 } from './digest.ts';
+import { parseDuration, ttlSeconds } from './mount-form.ts';
+import type { BaoPkiRoleProps } from './pki-role-form.ts';
+
+/**
+ * The managed field set, normalised so both sides of a diff are byte-comparable.
+ *
+ * ⚠️ KEY ORDER IS THE DIGEST. The props side and the live side are both built by the single
+ *   canonical() literal below, so `JSON.stringify` emits the same key order for each. Two
+ *   hand-written object literals would drift apart and produce a forever-diff nobody could
+ *   read from the plan output.
+ */
+export interface BaoPkiRoleCanonical {
+  allowBareDomains: boolean;
+  allowGlobDomains: boolean;
+  allowIpSans: boolean;
+  allowLocalhost: boolean;
+  allowSubdomains: boolean;
+  allowWildcardCertificates: boolean;
+  allowedDomains: readonly string[];
+  allowedDomainsTemplate: boolean;
+  clientFlag: boolean;
+  cnValidations: readonly string[];
+  enforceHostnames: boolean;
+  extKeyUsage: readonly string[];
+  generateLease: boolean;
+  keyBits: number;
+  keyType: string;
+  keyUsage: readonly string[];
+  /** ⚠️ `-1` means the duration prop did not parse — reconcile refuses rather than writing it. */
+  maxTtlSeconds: number;
+  noStore: boolean;
+  requireCn: boolean;
+  serverFlag: boolean;
+  signatureBits: number;
+  ttlSeconds: number;
+}
+
+/** ★ OpenBao's own `key_usage` default (path_roles.go:697-698) — what an omitted field becomes. */
+export const DEFAULT_KEY_USAGE: readonly string[] = [
+  'DigitalSignature',
+  'KeyAgreement',
+  'KeyEncipherment',
+];
+
+const sorted = (values: readonly string[]) => [...values].sort();
+
+/** ⚠️ Case-folded for the COMPARE only; the write keeps the author's casing.
+ *   Why, and what was never measured, is in the pki-role.ts header. `key_usage` gets the same
+ *   treatment as `ext_key_usage`, for the same reason — REASONED, not measured. */
+const foldedUsages = (values: readonly string[]) => sorted(values.map((v) => v.toLowerCase()));
+
+/** The one literal that fixes key order for both sides of the diff. */
+const canonical = (input: BaoPkiRoleCanonical): BaoPkiRoleCanonical => ({
+  allowBareDomains: input.allowBareDomains,
+  allowGlobDomains: input.allowGlobDomains,
+  allowIpSans: input.allowIpSans,
+  allowLocalhost: input.allowLocalhost,
+  allowSubdomains: input.allowSubdomains,
+  allowWildcardCertificates: input.allowWildcardCertificates,
+  allowedDomains: sorted(input.allowedDomains),
+  allowedDomainsTemplate: input.allowedDomainsTemplate,
+  clientFlag: input.clientFlag,
+  cnValidations: sorted(input.cnValidations),
+  enforceHostnames: input.enforceHostnames,
+  extKeyUsage: foldedUsages(input.extKeyUsage),
+  generateLease: input.generateLease,
+  keyBits: input.keyBits,
+  keyType: input.keyType,
+  keyUsage: foldedUsages(input.keyUsage),
+  maxTtlSeconds: input.maxTtlSeconds,
+  noStore: input.noStore,
+  requireCn: input.requireCn,
+  serverFlag: input.serverFlag,
+  signatureBits: input.signatureBits,
+  ttlSeconds: input.ttlSeconds,
+});
+
+const seconds = (text: string) => parseDuration(text) ?? -1;
+
+export const canonicalFromProps = (props: BaoPkiRoleProps): BaoPkiRoleCanonical =>
+  canonical({
+    allowBareDomains: props.allowBareDomains ?? false,
+    allowGlobDomains: props.allowGlobDomains ?? false,
+    allowIpSans: props.allowIpSans ?? false,
+    allowLocalhost: props.allowLocalhost ?? false,
+    allowSubdomains: props.allowSubdomains ?? false,
+    allowWildcardCertificates: props.allowWildcardCertificates ?? false,
+    allowedDomains: props.allowedDomains,
+    allowedDomainsTemplate: props.allowedDomainsTemplate ?? false,
+    clientFlag: props.clientFlag ?? true,
+    cnValidations: props.cnValidations ?? ['hostname'],
+    enforceHostnames: props.enforceHostnames ?? true,
+    extKeyUsage: props.extKeyUsage ?? [],
+    generateLease: props.generateLease ?? false,
+    keyBits: props.keyBits ?? 0,
+    keyType: props.keyType ?? 'rsa',
+    keyUsage: props.keyUsage ?? DEFAULT_KEY_USAGE,
+    maxTtlSeconds: seconds(props.maxTtl),
+    noStore: props.noStore ?? false,
+    requireCn: props.requireCn ?? true,
+    serverFlag: props.serverFlag ?? true,
+    signatureBits: props.signatureBits ?? 0,
+    ttlSeconds: seconds(props.ttl),
+  });
+
+const bool = (value: unknown, fallback: boolean) => (typeof value === 'boolean' ? value : fallback);
+
+const int = (value: unknown, fallback: number) =>
+  typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+
+const list = (value: unknown): readonly string[] =>
+  Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [];
+
+const str = (value: unknown, fallback: string) => (typeof value === 'string' ? value : fallback);
+
+/**
+ * ⚠️ AN ABSENT NEW FIELD READS AS ITS ZERO VALUE, NOT ITS SCHEMA DEFAULT. A role read always carries
+ *   the six new fields (ToResponseData, path_roles.go:1720-1780; `generate_lease` only when set,
+ *   and getRole upgrades a missing one to false at :1034), so the fallback only answers a body
+ *   that is not OpenBao's — and then "false"/"none" reads as drift rather than a false noop.
+ */
+export const canonicalFromLive = (live: Record<string, unknown>): BaoPkiRoleCanonical =>
+  canonical({
+    allowBareDomains: bool(live['allow_bare_domains'], false),
+    allowGlobDomains: bool(live['allow_glob_domains'], false),
+    allowIpSans: bool(live['allow_ip_sans'], false),
+    allowLocalhost: bool(live['allow_localhost'], false),
+    allowSubdomains: bool(live['allow_subdomains'], false),
+    allowWildcardCertificates: bool(live['allow_wildcard_certificates'], false),
+    allowedDomains: list(live['allowed_domains']),
+    allowedDomainsTemplate: bool(live['allowed_domains_template'], false),
+    clientFlag: bool(live['client_flag'], true),
+    cnValidations: list(live['cn_validations']),
+    enforceHostnames: bool(live['enforce_hostnames'], false),
+    extKeyUsage: list(live['ext_key_usage']),
+    generateLease: bool(live['generate_lease'], false),
+    keyBits: int(live['key_bits'], 0),
+    keyType: str(live['key_type'], 'rsa'),
+    keyUsage: list(live['key_usage']),
+    maxTtlSeconds: ttlSeconds(live['max_ttl']) ?? -1,
+    noStore: bool(live['no_store'], false),
+    requireCn: bool(live['require_cn'], false),
+    serverFlag: bool(live['server_flag'], true),
+    signatureBits: int(live['signature_bits'], 0),
+    ttlSeconds: ttlSeconds(live['ttl']) ?? -1,
+  });
+
+export const digestOf = (form: BaoPkiRoleCanonical): string => sha256(JSON.stringify(form));

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

@@ -0,0 +1,112 @@
+/**
+ * Bao.PkiRole's six fields added 2026-09-21. The part worth pinning: a role written BEFORE they
+ * were props carries OpenBao's defaults for them, and must still plan `noop`; a role that differs
+ * on any of them must plan `update`, because the full-replace write would reset it.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  type BaoPkiRoleProps,
+  attributesOf,
+  matches,
+  problems,
+  writeBody,
+} from './pki-role-form.ts';
+
+const PROPS: BaoPkiRoleProps = {
+  allowedDomains: ['svc.example.com'],
+  allowSubdomains: true,
+  maxTtl: '8760h',
+  name: 'host-cert',
+  ttl: '720h',
+};
+
+/** What OpenBao 2.6.2 answers for a role this resource wrote before the six were props. */
+const LIVE: Record<string, unknown> = {
+  allow_bare_domains: false,
+  allow_glob_domains: false,
+  allow_ip_sans: false,
+  allow_localhost: false,
+  allow_subdomains: true,
+  allow_wildcard_certificates: false,
+  allowed_domains: ['svc.example.com'],
+  allowed_domains_template: false,
+  client_flag: true,
+  cn_validations: ['hostname'],
+  enforce_hostnames: true,
+  ext_key_usage: [],
+  generate_lease: false,
+  key_bits: 0,
+  key_type: 'rsa',
+  key_usage: ['DigitalSignature', 'KeyAgreement', 'KeyEncipherment'],
+  max_ttl: 31536000,
+  no_store: false,
+  require_cn: true,
+  server_flag: true,
+  signature_bits: 0,
+  ttl: 2592000,
+};
+
+const same = (live: Record<string, unknown>, props: BaoPkiRoleProps = PROPS) =>
+  matches(attributesOf(props, live), props);
+
+describe('pki role — the six added fields', () => {
+  it("still plans noop for a role that carries OpenBao's defaults", () => {
+    assert.equal(same(LIVE), true);
+  });
+
+  it('plans update when live differs on any of them — the write would reset it', () => {
+    const drifted: [string, unknown][] = [
+      ['require_cn', false],
+      ['enforce_hostnames', false],
+      ['key_usage', ['DigitalSignature']],
+      ['allowed_domains_template', true],
+      ['no_store', true],
+      ['generate_lease', true],
+    ];
+    for (const [field, value] of drifted) {
+      assert.equal(same({ ...LIVE, [field]: value }), false, field);
+    }
+  });
+
+  it('reads key_usage as a set, case-folded, like ext_key_usage', () => {
+    const shuffled = {
+      ...LIVE,
+      key_usage: ['keyencipherment', 'DigitalSignature', 'KeyAgreement'],
+    };
+    assert.equal(same(shuffled), true);
+  });
+
+  it('matches declared values once live carries them', () => {
+    const props = { ...PROPS, keyUsage: ['DigitalSignature'], noStore: true, requireCn: false };
+    const live = { ...LIVE, key_usage: ['DigitalSignature'], no_store: true, require_cn: false };
+    assert.equal(same(live, props), true);
+    assert.equal(same(LIVE, props), false);
+  });
+
+  it("sends every one of them, with OpenBao's defaults when omitted", () => {
+    const body = writeBody(PROPS);
+    assert.equal(body['require_cn'], 'true');
+    assert.equal(body['enforce_hostnames'], 'true');
+    assert.equal(body['key_usage'], 'DigitalSignature,KeyAgreement,KeyEncipherment');
+    assert.equal(body['allowed_domains_template'], 'false');
+    assert.equal(body['no_store'], 'false');
+    assert.equal(body['generate_lease'], 'false');
+  });
+
+  it('sends an empty keyUsage as an empty string, which the server reads as no usages', () => {
+    assert.equal(writeBody({ ...PROPS, keyUsage: [] })['key_usage'], '');
+  });
+});
+
+describe('pki role problems', () => {
+  it('passes a sound declaration', () => {
+    assert.deepEqual(problems(PROPS), []);
+  });
+
+  it('refuses noStore with generateLease, empty domains and bad durations', () => {
+    assert.match(problems({ ...PROPS, generateLease: true, noStore: true }).join(), /noStore/);
+    assert.match(problems({ ...PROPS, allowedDomains: [] }).join(), /allowedDomains is empty/);
+    assert.match(problems({ ...PROPS, ttl: '4h30m' }).join(), /ttl=4h30m/);
+  });
+});

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

@@ -1,5 +1,13 @@
-import { sha256 } from './digest.ts';
-import { mountPath, parseDuration, ttlSeconds } from './mount-form.ts';
+import { mountPath, parseDuration } from './mount-form.ts';
+import {
+  type BaoPkiRoleCanonical,
+  DEFAULT_KEY_USAGE,
+  canonicalFromLive,
+  canonicalFromProps,
+  digestOf,
+} from './pki-role-canonical.ts';
+
+export type { BaoPkiRoleCanonical };
 
 /** ★ MEASURED: the OpenAPI enum for `key_type` is exactly these four, lowercase. */
 export type BaoPkiKeyType = 'any' | 'ec' | 'ed25519' | 'rsa';
@@ -56,34 +64,29 @@ export interface BaoPkiRoleProps {
   cnValidations?: readonly BaoPkiCnValidation[];
   /** Signature hash bits; `0` auto-detects from key length. One live role pins 256. */
   signatureBits?: number;
-}
-
-/**
- * The managed field set, normalised so both sides of a diff are byte-comparable.
- *
- * ⚠️ KEY ORDER IS THE DIGEST. The props side and the live side are both built by the single
- *   canonical() literal below, so `JSON.stringify` emits the same key order for each. Two
- *   hand-written object literals would drift apart and produce a forever-diff nobody could
- *   read from the plan output.
- */
-export interface BaoPkiRoleCanonical {
-  allowBareDomains: boolean;
-  allowGlobDomains: boolean;
-  allowIpSans: boolean;
-  allowLocalhost: boolean;
-  allowSubdomains: boolean;
-  allowWildcardCertificates: boolean;
-  allowedDomains: readonly string[];
-  clientFlag: boolean;
-  cnValidations: readonly string[];
-  extKeyUsage: readonly string[];
-  keyBits: number;
-  keyType: string;
-  /** ⚠️ `-1` means the duration prop did not parse — reconcile refuses rather than writing it. */
-  maxTtlSeconds: number;
-  serverFlag: boolean;
-  signatureBits: number;
-  ttlSeconds: number;
+  /**
+   * ★ THE SIX BELOW (added 2026-09-21) default to OpenBao's OWN values, not closed ones — a role this
+   *   resource wrote before they were props carries exactly those, so it still plans `noop`. The
+   *   write already sent them implicitly; see the header of pki-role-canonical.ts.
+   */
+  /** A request must carry a common_name. Default true. */
+  requireCn?: boolean;
+  /** Only valid host names in the CN and DNS SANs. Default true. */
+  enforceHostnames?: boolean;
+  /**
+   * Key usages minus the `KeyUsage` prefix. Default `DigitalSignature, KeyAgreement,
+   * KeyEncipherment`. ⚠️ `[]` is a real value — it removes every key usage — and is sent as such.
+   */
+  keyUsage?: readonly string[];
+  /** Allowed domains may use identity templates (`{{identity.entity.name}}`). Default false. */
+  allowedDomainsTemplate?: boolean;
+  /**
+   * Do not store issued certificates. Default false. ⛔ They can then be neither listed nor
+   *   revoked. ⚠️ Implies `generateLease: false`; declaring both true is refused (see problems).
+   */
+  noStore?: boolean;
+  /** Attach an OpenBao lease to every issued certificate. Default false — leases slow startup. */
+  generateLease?: boolean;
 }
 
 export interface BaoPkiRoleAttributes extends BaoPkiRoleCanonical {
@@ -96,84 +99,6 @@ export interface BaoPkiRoleAttributes extends BaoPkiRoleCanonical {
   digest: string;
 }
 
-const sorted = (values: readonly string[]) => [...values].sort();
-
-/** ⚠️ Case-folded for the COMPARE only; the write keeps the author's casing.
- *   Why, and what was never measured, is in the pki-role.ts header. */
-const foldedUsages = (values: readonly string[]) => sorted(values.map((v) => v.toLowerCase()));
-
-/** The one literal that fixes key order for both sides of the diff. */
-const canonical = (input: BaoPkiRoleCanonical): BaoPkiRoleCanonical => ({
-  allowBareDomains: input.allowBareDomains,
-  allowGlobDomains: input.allowGlobDomains,
-  allowIpSans: input.allowIpSans,
-  allowLocalhost: input.allowLocalhost,
-  allowSubdomains: input.allowSubdomains,
-  allowWildcardCertificates: input.allowWildcardCertificates,
-  allowedDomains: sorted(input.allowedDomains),
-  clientFlag: input.clientFlag,
-  cnValidations: sorted(input.cnValidations),
-  extKeyUsage: foldedUsages(input.extKeyUsage),
-  keyBits: input.keyBits,
-  keyType: input.keyType,
-  maxTtlSeconds: input.maxTtlSeconds,
-  serverFlag: input.serverFlag,
-  signatureBits: input.signatureBits,
-  ttlSeconds: input.ttlSeconds,
-});
-
-const seconds = (text: string) => parseDuration(text) ?? -1;
-
-export const canonicalFromProps = (props: BaoPkiRoleProps): BaoPkiRoleCanonical =>
-  canonical({
-    allowBareDomains: props.allowBareDomains ?? false,
-    allowGlobDomains: props.allowGlobDomains ?? false,
-    allowIpSans: props.allowIpSans ?? false,
-    allowLocalhost: props.allowLocalhost ?? false,
-    allowSubdomains: props.allowSubdomains ?? false,
-    allowWildcardCertificates: props.allowWildcardCertificates ?? false,
-    allowedDomains: props.allowedDomains,
-    clientFlag: props.clientFlag ?? true,
-    cnValidations: props.cnValidations ?? ['hostname'],
-    extKeyUsage: props.extKeyUsage ?? [],
-    keyBits: props.keyBits ?? 0,
-    keyType: props.keyType ?? 'rsa',
-    maxTtlSeconds: seconds(props.maxTtl),
-    serverFlag: props.serverFlag ?? true,
-    signatureBits: props.signatureBits ?? 0,
-    ttlSeconds: seconds(props.ttl),
-  });
-
-const bool = (value: unknown, fallback: boolean) => (typeof value === 'boolean' ? value : fallback);
-
-const int = (value: unknown, fallback: number) =>
-  typeof value === 'number' && Number.isFinite(value) ? value : fallback;
-
-const list = (value: unknown): readonly string[] =>
-  Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [];
-
-const str = (value: unknown, fallback: string) => (typeof value === 'string' ? value : fallback);
-
-export const canonicalFromLive = (live: Record<string, unknown>): BaoPkiRoleCanonical =>
-  canonical({
-    allowBareDomains: bool(live['allow_bare_domains'], false),
-    allowGlobDomains: bool(live['allow_glob_domains'], false),
-    allowIpSans: bool(live['allow_ip_sans'], false),
-    allowLocalhost: bool(live['allow_localhost'], false),
-    allowSubdomains: bool(live['allow_subdomains'], false),
-    allowWildcardCertificates: bool(live['allow_wildcard_certificates'], false),
-    allowedDomains: list(live['allowed_domains']),
-    clientFlag: bool(live['client_flag'], true),
-    cnValidations: list(live['cn_validations']),
-    extKeyUsage: list(live['ext_key_usage']),
-    keyBits: int(live['key_bits'], 0),
-    keyType: str(live['key_type'], 'rsa'),
-    maxTtlSeconds: ttlSeconds(live['max_ttl']) ?? -1,
-    serverFlag: bool(live['server_flag'], true),
-    signatureBits: int(live['signature_bits'], 0),
-    ttlSeconds: ttlSeconds(live['ttl']) ?? -1,
-  });
-
 /** ⚠️ Same rendering auth-role-form.ts uses, so `720h` and `2592000` read alike in a plan. */
 const ttlText = (value: number) => {
   if (value < 0) return '';
@@ -183,8 +108,6 @@ const ttlText = (value: number) => {
   return `${String(value)}s`;
 };
 
-export const digestOf = (form: BaoPkiRoleCanonical) => sha256(JSON.stringify(form));
-
 export const rolePath = (props: { name: string; mount?: string }) =>
   `${mountPath(props.mount ?? 'pki')}/roles/${props.name}`;
 
@@ -216,6 +139,10 @@ export const attributesOf = (
  * ★ `ext_key_usage` is OMITTED when empty rather than sent as `ext_key_usage=`. The write
  *   replaces the whole role, so an absent field already lands on the `[]` default, and
  *   omitting sidesteps how an empty value would be encoded.
+ * ⚠️ `key_usage` CANNOT BE OMITTED THAT WAY — its default is NOT empty — so it is always sent, and
+ *   an empty declaration goes over as `""`. That encoding is now READ, not guessed: for a
+ *   comma-string-slice field, go-secure-stdlib parseutil.ParseCommaStringSlice (:389-392)
+ *   answers `""` with an empty list.
  *
  * ★ THE BODY FOR `PUT <mount>/roles/<name>`, ALL STRINGS — the same `k=v` pairs `bao write` sent.
  */
@@ -237,6 +164,12 @@ export const writeBody = (props: BaoPkiRoleProps): Record<string, string> => {
     signature_bits: String(form.signatureBits),
     ttl: props.ttl,
     max_ttl: props.maxTtl,
+    require_cn: String(form.requireCn),
+    enforce_hostnames: String(form.enforceHostnames),
+    key_usage: (props.keyUsage ?? DEFAULT_KEY_USAGE).join(','),
+    allowed_domains_template: String(form.allowedDomainsTemplate),
+    no_store: String(form.noStore),
+    generate_lease: String(form.generateLease),
   };
   const usages = props.extKeyUsage ?? [];
   if (usages.length > 0) body['ext_key_usage'] = usages.join(',');
@@ -246,3 +179,36 @@ export const writeBody = (props: BaoPkiRoleProps): Record<string, string> => {
 /** True when live already matches the declaration on every managed field. */
 export const matches = (attributes: BaoPkiRoleAttributes, props: BaoPkiRoleProps) =>
   attributes.digest === digestOf(canonicalFromProps(props));
+
+/**
+ * Declarations reconcile must refuse rather than write. diff routes any of these to `update` so the
+ * refusal is seen on the next deploy, never hidden behind a `noop`.
+ *
+ * ⚠️ `noStore` WITH `generateLease` IS NOT AN ERROR ON THE SERVER — pathRoleCreate stores
+ *   generate_lease false and adds a warning (path_roles.go:1250-1256) — so the role would read back
+ *   different from its declaration and plan `update` forever. Refused here instead.
+ */
+export const problems = (props: BaoPkiRoleProps): readonly string[] => {
+  const found: string[] = [];
+  if (props.allowedDomains.length === 0) {
+    found.push(
+      'allowedDomains is empty. With allow_any_name false that role can issue no certificate at all.',
+    );
+  }
+  const bad = [
+    ['ttl', props.ttl],
+    ['maxTtl', props.maxTtl],
+  ].filter(([, text]) => parseDuration(text ?? '') === undefined);
+  if (bad.length > 0) {
+    found.push(
+      `${bad.map(([k, v]) => `${k ?? ''}=${v ?? ''}`).join(', ')} is not a duration OpenBao ` +
+        'parses (expect 30m, 720h, 8760h or 0).',
+    );
+  }
+  if (props.noStore === true && props.generateLease === true) {
+    found.push(
+      'noStore and generateLease are both true; OpenBao keeps no_store and drops the lease.',
+    );
+  }
+  return found;
+};