@homeflare/alchemy 0.1.0

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

@@ -0,0 +1,248 @@
+import { sha256 } from './digest.ts';
+import { mountPath, parseDuration, ttlSeconds } from './mount-form.ts';
+
+/** ★ MEASURED: the OpenAPI enum for `key_type` is exactly these four, lowercase. */
+export type BaoPkiKeyType = 'any' | 'ec' | 'ed25519' | 'rsa';
+
+/** ★ MEASURED: live roles carry `["hostname"]` or the default `["email","hostname"]`. */
+export type BaoPkiCnValidation = 'disabled' | 'email' | 'hostname';
+
+export interface BaoPkiRoleProps {
+  /** Role name, as `pki/roles/{name}` takes it. */
+  name: string;
+  /** Mount holding the engine. Defaults to `pki` — the only PKI mount live today. */
+  mount?: string;
+  /**
+   * Domains this role may issue for.
+   *
+   * ⛔ AN EMPTY LIST IS REFUSED IN reconcile, NOT WRITTEN. With `allow_any_name` false — the
+   *   default, and what all eight live roles use — a role with no allowed domains can issue
+   *   nothing, so a mistyped or unresolved prop would quietly brick every renewal under it.
+   */
+  allowedDomains: readonly string[];
+  /** Permit `foo.<allowed domain>`. Default false. */
+  allowSubdomains?: boolean;
+  /** Permit the allowed domain itself as the CN. Default false. */
+  allowBareDomains?: boolean;
+  /** Treat `*` inside an allowed domain as a glob. Default false. */
+  allowGlobDomains?: boolean;
+  /**
+   * Default certificate lifetime, as a duration string (`720h`).
+   *
+   * ⚠️ WRITTEN AS A DURATION, READ BACK AS SECONDS — `ttl` and `max_ttl` both carry
+   *   `format: seconds` in the OpenAPI and come back as integers (`2592000`). The prop
+   *   string reaches `bao write` verbatim; the compare happens in seconds. See canonical().
+   */
+  ttl: string;
+  /** Ceiling on a requested lifetime, as a duration string (`8760h`). */
+  maxTtl: string;
+  /** Key algorithm. Default `rsa` — OpenBao's own default. */
+  keyType?: BaoPkiKeyType;
+  /** Key size; `0` means "engine default for keyType". rsa 2048/3072/4096, ec 224/256/384/521. */
+  keyBits?: number;
+  /** Flag certificates for TLS server auth. ⚠️ OpenBao defaults this TRUE. */
+  serverFlag?: boolean;
+  /** Flag certificates for TLS client auth. ⚠️ OpenBao defaults this TRUE. */
+  clientFlag?: boolean;
+  /** Extended key usages minus the `ExtKeyUsage` prefix (`ServerAuth`). Empty on all 8 live roles. */
+  extKeyUsage?: readonly string[];
+  /** Permit IP SANs. ⚠️ OpenBao defaults TRUE; this resource defaults FALSE — see pki-role.ts. */
+  allowIpSans?: boolean;
+  /** Permit `localhost`/`localdomain` CNs. ⚠️ OpenBao TRUE, this resource FALSE. */
+  allowLocalhost?: boolean;
+  /** Permit wildcard CNs. ⚠️ OpenBao TRUE, this resource FALSE. */
+  allowWildcardCertificates?: boolean;
+  /** CN validations to run. ⚠️ OpenBao `["email","hostname"]`, this resource `["hostname"]`. */
+  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;
+}
+
+export interface BaoPkiRoleAttributes extends BaoPkiRoleCanonical {
+  name: string;
+  mount: string;
+  /** Human rendering of ttlSeconds — the compare uses the seconds, this is for the plan. */
+  ttl: string;
+  maxTtl: string;
+  /** SHA-256 of the canonical form — safe to persist; see policy.ts. */
+  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 '';
+  if (value !== 0 && value % 86400 === 0) return `${String(value / 86400)}d`;
+  if (value !== 0 && value % 3600 === 0) return `${String(value / 3600)}h`;
+  if (value !== 0 && value % 60 === 0) return `${String(value / 60)}m`;
+  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}`;
+
+export const attributesOf = (
+  props: BaoPkiRoleProps,
+  live: Record<string, unknown>,
+): BaoPkiRoleAttributes => {
+  const form = canonicalFromLive(live);
+  return {
+    ...form,
+    name: props.name,
+    mount: mountPath(props.mount ?? 'pki'),
+    ttl: ttlText(form.ttlSeconds),
+    maxTtl: ttlText(form.maxTtlSeconds),
+    digest: digestOf(form),
+  };
+};
+
+/**
+ * ⚠️ ARRAYS GO OVER AS COMMA-JOINED STRINGS. `allowed_domains` and `ext_key_usage` are
+ *   documented as "a comma-separated string or list"; `cn_validations` is not, so its
+ *   splitting is REASONED, not measured. reconcile re-reads and re-compares after every
+ *   write, so a value that arrived unsplit fails loudly instead of landing wrong.
+ *
+ * ⚠️ TTLs GO OVER AS THE AUTHOR'S OWN DURATION STRING, never as a re-rendered one — so this
+ *   never has to know whether OpenBao's parser accepts the `d` suffix ttlText() produces for
+ *   display. Rendering is for humans; the wire only ever sees what was declared.
+ *
+ * ★ `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.
+ *
+ * ★ THE BODY FOR `PUT <mount>/roles/<name>`, ALL STRINGS — the same `k=v` pairs `bao write` sent.
+ */
+export const writeBody = (props: BaoPkiRoleProps): Record<string, string> => {
+  const form = canonicalFromProps(props);
+  const body: Record<string, string> = {
+    allowed_domains: form.allowedDomains.join(','),
+    allow_bare_domains: String(form.allowBareDomains),
+    allow_glob_domains: String(form.allowGlobDomains),
+    allow_subdomains: String(form.allowSubdomains),
+    allow_ip_sans: String(form.allowIpSans),
+    allow_localhost: String(form.allowLocalhost),
+    allow_wildcard_certificates: String(form.allowWildcardCertificates),
+    cn_validations: form.cnValidations.join(','),
+    client_flag: String(form.clientFlag),
+    server_flag: String(form.serverFlag),
+    key_type: form.keyType,
+    key_bits: String(form.keyBits),
+    signature_bits: String(form.signatureBits),
+    ttl: props.ttl,
+    max_ttl: props.maxTtl,
+  };
+  const usages = props.extKeyUsage ?? [];
+  if (usages.length > 0) body['ext_key_usage'] = usages.join(',');
+  return body;
+};
+
+/** True when live already matches the declaration on every managed field. */
+export const matches = (attributes: BaoPkiRoleAttributes, props: BaoPkiRoleProps) =>
+  attributes.digest === digestOf(canonicalFromProps(props));

package/src/openbao/pki-role.ts

@@ -0,0 +1,202 @@
+/**
+ * An OpenBao PKI role — the policy a future issuance is checked against, and nothing else.
+ *
+ * ⛔ THE ROLE IS THE POLICY, NEVER THE CERTIFICATE. Nothing here touches `pki/issue/*` (which
+ *   RETURNS a private key) or `pki/root/generate/*` (which CREATES one). Every value this
+ *   resource stores is a domain name, a flag, a bit count or a TTL — safe to sit in Alchemy's
+ *   UNENCRYPTED Postgres state. See policy.ts for why that line is load-bearing here.
+ *
+ * ⛔ `bao write pki/roles/<name>` REPLACES THE WHOLE ROLE — it is not a merge. OpenBao builds
+ *   a fresh role entry from the request, so every field left out reverts to its SCHEMA
+ *   DEFAULT. MEASURED 2026-09-13 against the live OpenBao 2.6.2, from its own
+ *   `sys/internal/specs/openapi` cross-read against all eight live `pki/roles/*`, four of
+ *   those defaults are WIDER than what this estate actually runs:
+ *
+ *     allow_ip_sans                default true                  — false on 5 of the 8 roles
+ *     allow_localhost              default true                  — false on 6 of the 8
+ *     allow_wildcard_certificates  default true                  — false on 6 of the 8
+ *     cn_validations               default ["email","hostname"]  — ["hostname"] on 5 of the 8
+ *
+ *   A resource that managed only the eleven fields the brief named would therefore, on any
+ *   unrelated TTL edit, silently re-open wildcards and localhost on six production roles.
+ *   That is why those four are props in pki-role-form.ts though they were not in the brief,
+ *   and why their default there is the CLOSED value rather than OpenBao's open one.
+ *
+ * ★ NARROWING IS THE FAIL-SAFE DIRECTION. A default tighter than OpenBao's can only refuse a
+ *   certificate that should have been issued — loud, and cured by declaring the field. A
+ *   default looser than OpenBao's issues one that should have been refused, in silence.
+ *
+ * ⚠️ WHAT WAS NOT MEASURED. Only reads were run against the live engine; no `bao write`
+ *   happened, so nothing below is a verified round-trip. Two consequences carried into the
+ *   form file: every live role has `ext_key_usage: []`, so the stored casing of a non-empty
+ *   list was never observed (the compare folds case because OpenBao matches these
+ *   case-insensitively at issuance); and every live role has exactly ONE allowed domain, so
+ *   whether OpenBao preserves list order was never observed either (the compare sorts,
+ *   because allowed_domains is a set). Both choices can only mask a cosmetic difference,
+ *   never a policy one — but neither is a measurement.
+ *
+ * ★ `defaultRemovalPolicy: 'retain'` — see the delete comment below. Opt in with
+ *   `.pipe(RemovalPolicy.destroy())`; see resource.ts in house/proxmox.
+ */
+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, baoRead, baoWrite } from './bao-http.ts';
+import { mountPath, parseDuration } from './mount-form.ts';
+import {
+  type BaoPkiRoleAttributes,
+  type BaoPkiRoleProps,
+  attributesOf,
+  matches,
+  rolePath,
+  writeBody,
+} from './pki-role-form.ts';
+
+export type { BaoPkiRoleAttributes, BaoPkiRoleProps };
+
+export interface BaoPkiRole extends Resource<
+  'Bao.PkiRole',
+  BaoPkiRoleProps,
+  BaoPkiRoleAttributes,
+  never,
+  HttpClient.HttpClient
+> {}
+
+export const BaoPkiRole = Resource<BaoPkiRole>('Bao.PkiRole', {
+  defaultRemovalPolicy: 'retain',
+});
+
+const readRole = (props: BaoPkiRoleProps) =>
+  Effect.gen(function* () {
+    const live = yield* baoRead(rolePath(props));
+    if (live === undefined) return undefined;
+    return attributesOf(props, live);
+  });
+
+/** Duration props `bao write` must never see — reconcile turns these into a refusal. */
+const badDurations = (props: BaoPkiRoleProps) =>
+  [['ttl', props.ttl] as const, ['maxTtl', props.maxTtl] as const].filter(
+    ([, text]) => parseDuration(text) === undefined,
+  );
+
+export const BaoPkiRoleProvider = () =>
+  Provider.effect(
+    BaoPkiRole,
+    Effect.succeed(
+      BaoPkiRole.Provider.of({
+        /**
+         * ⛔ `bao list pki/roles` IS NOT A LIST OF THINGS THIS OWNS. All eight roles in the
+         *   live engine answer it, and every one of them predates this resource. Returning
+         *   them would invite Alchemy to adopt — and then delete — roles it never created.
+         */
+        list: () => Effect.succeed([]),
+
+        read: Effect.fn(function* ({ olds }) {
+          return yield* readRole(olds);
+        }),
+
+        /**
+         * ⛔ IT COMPARES A DIGEST OF THE LIVE ROLE, NOT THE STORED ONE. The attributes fed to
+         *   `matches` are always freshly derived from a live read in this same operation, so
+         *   a role widened by hand in the OpenBao UI still reads as drift — which is the
+         *   whole reason the check-* gates exist. Comparing one digest rather than sixteen
+         *   fields is also what stops a field being added to props and quietly forgotten in
+         *   the comparison.
+         */
+        diff: Effect.fn(function* ({ news, output }) {
+          if (output === undefined || !isResolved(news)) return undefined;
+          /**
+           * ⚠️ A ROLE IS IDENTIFIED BY MOUNT **AND** NAME. Moving a declaration to another
+           *   engine is a different object under a different CA, never an in-place edit —
+           *   `replace`, so Alchemy creates the new one and retires the old.
+           */
+          if (mountPath(news.mount ?? 'pki') !== output.mount)
+            return { action: 'replace' } as const;
+          /**
+           * ⚠️ A DECLARATION reconcile WOULD REFUSE MUST NEVER PLAN AS noop. An empty
+           *   allowedDomains, or a duration OpenBao cannot parse, can compare equal to a
+           *   live role already in that state — and a noop there hides the refusal behind a
+           *   clean plan until the next deploy. Route it to reconcile, which says why.
+           */
+          if (news.allowedDomains.length === 0 || badDurations(news).length > 0) {
+            return { action: 'update' } as const;
+          }
+          const live = yield* readRole(news);
+          if (live === undefined) return { action: 'update' } as const;
+          return matches(live, news)
+            ? ({ action: 'noop' } as const)
+            : ({ action: 'update' } as const);
+        }),
+
+        reconcile: Effect.fn(function* ({ news }) {
+          const path = rolePath(news);
+          /**
+           * ⛔ AN EMPTY allowedDomains IS A REFUSAL, NOT AN EMPTY ROLE. `allow_any_name` is
+           *   false on every live role, so a role with no allowed domains can issue NOTHING —
+           *   and an unresolved or mistyped prop reads exactly like an author who meant it.
+           *   policy.ts refuses an empty fragment directory for the same reason.
+           */
+          if (news.allowedDomains.length === 0) {
+            return yield* Effect.die(
+              new Error(
+                `Bao.PkiRole ${path}: allowedDomains is empty. With allow_any_name false ` +
+                  'that role can issue no certificate at all.',
+              ),
+            );
+          }
+          const bad = badDurations(news);
+          if (bad.length > 0) {
+            return yield* Effect.die(
+              new Error(
+                `Bao.PkiRole ${path}: ${bad.map(([k, v]) => `${k}=${v}`).join(', ')} ` +
+                  'is not a duration OpenBao parses (expect 30m, 720h, 8760h or 0).',
+              ),
+            );
+          }
+          const live = yield* readRole(news);
+          if (live === undefined || !matches(live, news)) {
+            yield* baoWrite('PUT', path, writeBody(news));
+          }
+          const after = yield* readRole(news);
+          if (after === undefined) {
+            return yield* Effect.die(
+              new Error(`Bao.PkiRole ${path}: write reported success but the role is absent.`),
+            );
+          }
+          /**
+           * ⛔ THE WRITE IS NOT TRUSTED, IT IS RE-READ AND RE-COMPARED. A write succeeds (2xx)
+           *   for a field it accepted but stored differently — the live worry being the
+           *   comma-joined list values in writeBody, whose splitting is documented for
+           *   allowed_domains and ext_key_usage but NOT for cn_validations. Without this
+           *   check a role could land with `cn_validations: ["email,hostname"]`, report
+           *   success, and then refuse every renewal at issuance time instead.
+           */
+          if (!matches(after, news)) {
+            return yield* Effect.die(
+              new Error(
+                `Bao.PkiRole ${path}: wrote cleanly but the role read back different. ` +
+                  'OpenBao stored something other than what was declared — inspect with ' +
+                  `\`bao read ${path}\` before retrying.`,
+              ),
+            );
+          }
+          return after;
+        }),
+
+        /**
+         * ⛔ DELETING A ROLE DOES NOT REVOKE THE CERTIFICATES IT ISSUED — they stay valid to
+         *   their own expiry, so this is quiet now and loud much later: every renewal through
+         *   the role fails once the current certificate runs out. MEASURED: the live roles
+         *   carry ttl 604800 to 31536000 seconds, so the fuse on `rpi5-otel-client` is a full
+         *   year. Idempotent as Alchemy requires — already gone is success — but retain is
+         *   the default for exactly this reason.
+         */
+        delete: Effect.fn(function* ({ output }) {
+          yield* baoDelete(rolePath(output));
+          return undefined;
+        }),
+      }),
+    ),
+  );

package/src/openbao/policy-assembly.test.ts

@@ -0,0 +1,28 @@
+/**
+ * The refusal that stands between a bad checkout and a policy with every grant revoked.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { isEmptyAssembly } from './policy-assembly.ts';
+
+describe('isEmptyAssembly', () => {
+  it('refuses a directory with no fragment files', () => {
+    assert.equal(isEmptyAssembly(0, ''), true);
+  });
+
+  // ⛔ The case the first guard missed: files exist, grants do not.
+  it('refuses fragments that are empty or whitespace', () => {
+    assert.equal(isEmptyAssembly(1, '\n'), true);
+    assert.equal(isEmptyAssembly(2, '   \n\t\n'), true);
+  });
+
+  it('refuses fragments that carry comments but no path grant', () => {
+    assert.equal(isEmptyAssembly(1, '# homeflare-agent\n# grants follow\n'), true);
+  });
+
+  it('allows an assembly with at least one path grant, indented or not', () => {
+    const kv = '# kv\npath "kv/data/apps/*" {\n  capabilities = ["read"]\n}\n';
+    assert.equal(isEmptyAssembly(1, kv), false);
+    assert.equal(isEmptyAssembly(1, '  path "sys/mounts" { capabilities = ["read"] }\n'), false);
+  });
+});

package/src/openbao/policy-assembly.ts

@@ -0,0 +1,13 @@
+/**
+ * Whether an assembled policy would carry NO GRANT — the one write `Bao.Policy` must refuse.
+ *
+ * ⛔ EMPTY MEANS NO `path` GRANT, NOT NO FILES. Writing `sys/policies/acl/<name>` with nothing in it
+ *   SILENTLY REVOKES every grant the policy carries, for every token bound to it. The first guard
+ *   only counted fragment files, so a directory whose one fragment was empty, whitespace or
+ *   comments — a truncated edit, a bad checkout — assembled to text with no grant in it, passed,
+ *   and would have replaced the live policy with nothing. Found by grok's review on 2026-09-14.
+ * ★ A GRANT IS A `path "…"` STANZA, the unit apply-agent-policy.sh counts and `grantsOf` in
+ *   policy.ts reports. Leading whitespace is allowed here, so an indented stanza still counts.
+ */
+export const isEmptyAssembly = (parts: number, joined: string): boolean =>
+  parts === 0 || !/^\s*path\s+"/m.test(joined);

package/src/openbao/policy-wire.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Bao.Policy's calls against a fake that behaves like OpenBao where it matters: it STRIPS the
+ * policy's trailing newline on write (measured on the live server — see digest.ts), answers 404 for
+ * a policy it does not have, and 204 for a delete whether or not the policy existed.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { BaoError } from './bao-status.ts';
+import { sha256 } from './digest.ts';
+import { type Seen, run, runFailure, withFake } from './fake-bao.ts';
+import { deletePolicy, readPolicy, writePolicy } from './policy-wire.ts';
+
+const PREFIX = '/v1/sys/policies/acl/';
+
+const policyStore = () => {
+  const policies = new Map<string, string>();
+  return (seen: Seen) => {
+    const name = seen.path.slice(PREFIX.length);
+    if (seen.method === 'PUT') {
+      const { policy } = JSON.parse(seen.body) as { policy: string };
+      policies.set(name, policy.replace(/\n+$/, ''));
+      return { status: 204 };
+    }
+    if (seen.method === 'DELETE') {
+      policies.delete(name);
+      return { status: 204 };
+    }
+    const policy = policies.get(name);
+    return policy === undefined
+      ? { json: { errors: [] }, status: 404 }
+      : { json: { data: { name, policy } }, status: 200 };
+  };
+};
+
+/** Two fragments, each followed by a newline — exactly how policy.ts assembles them. */
+const ASSEMBLED = 'path "kv/data/a" {\n  capabilities = ["read"]\n}\n' + 'path "kv/data/b" {}\n';
+
+describe('policy wire', () => {
+  it('reads a policy that was never written as absent', async () => {
+    await withFake(policyStore(), async (bao) => {
+      assert.equal(await run({ BAO_ADDR: bao.address }, readPolicy('zz-new-policy')), '');
+    });
+  });
+
+  // ⛔ THE FOREVER-DIFF. Live text comes back one newline short; the digests must still agree, or
+  //    every plan says `update` and reconcile rewrites a policy that already matches.
+  it('round-trips through the stripped newline with equal digests', async () => {
+    await withFake(policyStore(), async (bao) => {
+      const env = { BAO_ADDR: bao.address };
+      await run(env, writePolicy('homeflare-llm', ASSEMBLED));
+      assert.equal(bao.seen[0]?.method, 'PUT');
+      assert.equal(bao.seen[0]?.path, `${PREFIX}homeflare-llm`);
+      assert.deepEqual(JSON.parse(bao.seen[0]?.body ?? ''), { policy: ASSEMBLED });
+      const live = await run(env, readPolicy('homeflare-llm'));
+      assert.notEqual(live, ASSEMBLED, 'the fake strips the newline, as OpenBao does');
+      assert.equal(sha256(live), sha256(ASSEMBLED));
+    });
+  });
+
+  it('fails a refused read (403) instead of calling the policy absent', async () => {
+    await withFake(
+      () => ({ json: { errors: ['permission denied'] }, status: 403 }),
+      async (bao) => {
+        const error = await runFailure({ BAO_ADDR: bao.address }, readPolicy('homeflare-admin'));
+        assert.ok(error instanceof BaoError);
+        assert.equal(error.status, 403);
+      },
+    );
+  });
+
+  it('fails a 200 that carries no policy text', async () => {
+    await withFake(
+      () => ({ json: { data: { name: 'x' } }, status: 200 }),
+      async (bao) => {
+        const error = await runFailure({ BAO_ADDR: bao.address }, readPolicy('x'));
+        assert.match(String(error), /no data\.policy/);
+      },
+    );
+  });
+
+  it('deletes idempotently: a policy already gone is success', async () => {
+    await withFake(
+      () => ({ json: { errors: [] }, status: 404 }),
+      async (bao) => {
+        await run({ BAO_ADDR: bao.address }, deletePolicy('zz-gone'));
+        assert.equal(bao.seen[0]?.method, 'DELETE');
+      },
+    );
+  });
+});

package/src/openbao/policy-wire.ts

@@ -0,0 +1,53 @@
+/**
+ * The three OpenBao calls Bao.Policy makes — read, write and delete of `sys/policies/acl/<name>`.
+ * Split from policy.ts so the trailing-newline round trip can be tested against a fake server.
+ */
+import * as Effect from 'effect/Effect';
+import { baoDelete, baoRead, baoWrite } from './bao-http.ts';
+import { BaoError } from './bao-status.ts';
+
+/** The endpoint the CLI's policy commands used — openbao v2.6.2 api/sys_policy.go:60, :100, :122. */
+export const policyPath = (name: string) => `sys/policies/acl/${name}`;
+
+/**
+ * The live policy text, or '' when the policy is genuinely absent. Anything else FAILS.
+ *
+ * 🔴 THE ABSENCE WORDING WAS THE POLICY COMMAND'S OWN, AND ASSUMING OTHERWISE MADE A NEW POLICY
+ *   UNCREATABLE. `No value found at` was measured for `bao read`; `bao policy read` never printed
+ *   it. Its API client turned a 404 into an empty string and the CLI reported that in its own
+ *   words — openbao v2.6.2 api/sys_policy.go:65-67 and command/policy_read.go:85-87:
+ *
+ *     No policy named: <name>          exit 2
+ *
+ *   So `read` on a policy that did not exist yet FAILED instead of answering absent, and
+ *   `reconcile` failed at its own pre-write read. Every policy declared so far already existed,
+ *   which is the only reason nothing broke. MEASURED 2026-09-14 under the admin lane —
+ *   `bao policy read zz-probe-absent-policy-4c1e` printed exactly that line and exited 2. (The
+ *   agent lane cannot measure it: it is refused `sys/policies/acl` with a 403 first.)
+ * ★ THE WORDING PROBLEM IS GONE WITH THE CLI. The line above was the CLI's rendering of the 404 that
+ *   the server returns for a missing policy (vault/logical_system.go handlePoliciesRead returns no
+ *   response, which RespondErrorCommon turns into 404). That status is now read directly, and a
+ *   refused read is a 403 — two codes, no text to confuse.
+ *
+ * ⚠️ `data.policy` IS THE TEXT, and a 200 without it is a failure, as it was in the CLI's client
+ *   ("no policy found in response", api/sys_policy.go:81-85).
+ */
+export const readPolicy = (name: string) =>
+  Effect.flatMap(baoRead(policyPath(name)), (data) => {
+    if (data === undefined) return Effect.succeed('');
+    const text = data['policy'];
+    return typeof text === 'string'
+      ? Effect.succeed(text)
+      : Effect.fail(new BaoError(200, 'GET', policyPath(name), ['no data.policy in the response']));
+  });
+
+/**
+ * ★ THE HCL TRAVELS IN THE REQUEST BODY (`{"policy": …}`, api/sys_policy.go:96-101). The CLI path
+ *   needed a scoped temp file because passing HCL on argv would have put every grant in the process
+ *   list; a JSON body never reaches argv, so the temp file is gone with it.
+ */
+export const writePolicy = (name: string, hcl: string) =>
+  baoWrite('PUT', policyPath(name), { policy: hcl });
+
+/** Deleting a policy that is already gone answers success (handlePoliciesDelete returns nothing). */
+export const deletePolicy = (name: string) => baoDelete(policyPath(name));