@homeflare/alchemy 0.37.5 → 0.37.6

package/dist/proxmox/node-network-wire.d.ts

@@ -54,14 +54,17 @@ export interface NodeNetworkAttributes {
  *   `{"errors":{"iface":"interface does not exist"},"data":null,"message":"Parameter verification
  *   failed.\n"}` at HTTP 400 — a THIRD shape, different from every other migrated family's
  *   measured 500. `@distilled.cloud/proxmox` types this as a genuine typed error,
- *   `ParameterVerificationFailed` (`errors.ts`), carrying the per-field `errors` object rather
- *   than collapsing it to an opaque `BadRequest` — PVE's OWN 400 is never one shape (it is
- *   whatever the endpoint's parameter verification rejected), so `errors.ts`'s own header spells
- *   out why this ONE typed error is global rather than per-operation.
- * ⛔ ONLY THIS EXACT SIGNAL MEANS ABSENT, EVEN WITH THE FOLD BELOW. A different 400 reason, a
- *   permission gap, a network blip, or ANY OTHER `ParameterVerificationFailed` reason is never
- *   read as "this interface is not there" — `diff` calls this directly and propagates every one
- *   of them loudly.
+ *   `NetworkInterfaceNotFound` (`nodes.ts`, generated from `patches/nodes/network-errors.json`),
+ *   attached ONLY to `getNodeNetwork`'s error union and matched by the SDK's own
+ *   `errorEnvelope`/`matchTypedError` against the EXACT sole-field body `errors.iface ===
+ *   "interface does not exist"` — the precision the code here used to check by hand
+ *   (`error.errors['iface'] === '…'`) is now the SDK's own matcher contract, not this file's.
+ *   Any 400 that fails that exact match (a different field, a different message, more than one
+ *   field) decodes as the generic `ParameterVerificationFailed` instead, never this tag.
+ * ⛔ ONLY THIS EXACT SIGNAL MEANS ABSENT, EVEN WITH THE FOLD BELOW. A different 400 reason
+ *   (`ParameterVerificationFailed`), a permission gap, a network blip, or any other failure is
+ *   never read as "this interface is not there" — `diff` calls this directly and propagates
+ *   every one of them loudly.
  */
 export declare const readInterfaceOrFail: (props: NodeNetworkProps) => Effect.Effect<typeof UNREADABLE | NodeNetworkAttributes | undefined, import("@distilled.cloud/caddy").BadGateway | import("@distilled.cloud/caddy").BadRequest | import("@distilled.cloud/caddy").ConfigError | import("@distilled.cloud/caddy").Conflict | Error | import("@distilled.cloud/caddy").Forbidden | import("@distilled.cloud/caddy").GatewayTimeout | import("effect/unstable/http/HttpClientError").HttpClientError | import("@distilled.cloud/caddy").InternalServerError | import("@distilled.cloud/caddy").Locked | import("@distilled.cloud/caddy").NotFound | import("@distilled.cloud/proxmox/Errors").ParameterVerificationFailed | import("@distilled.cloud/proxmox/Errors").ProxmoxParseError | import("./distilled-pve.ts").PveClusterExhausted | import("@distilled.cloud/caddy").ServiceUnavailable | import("effect/Cause").TimeoutError | import("@distilled.cloud/caddy").TooManyRequests | import("@distilled.cloud/caddy").Unauthorized | import("@distilled.cloud/proxmox/Errors").UnknownProxmoxError | import("@distilled.cloud/caddy").UnprocessableEntity, import("effect/unstable/http/HttpClient").HttpClient>;
 /**
@@ -76,8 +79,9 @@ export declare const readInterfaceOrFail: (props: NodeNetworkProps) => Effect.Ef
  *   interrupted-create recovery, and Apply.ts's delete recovery, all call `read` with
  *   `output: undefined` and NO catch of their own (`Plan.ts` v2.0.0-beta.79 ~line 1308) — and
  *   Plan.ts fails the WHOLE PLAN, every other resource included, if that call throws. A malformed
- *   `iface` in ONE brand-new declaration (a DIFFERENT `ParameterVerificationFailed` than the
- *   absence one) would abort `bun run plan` for the entire stack under the precise-only design,
+ *   `iface` in ONE brand-new declaration (a `ParameterVerificationFailed`, DIFFERENT from the
+ *   `NetworkInterfaceNotFound` absence tag) would abort `bun run plan` for the entire stack under
+ *   the precise-only design,
  *   where every other migrated family instead defers that same malformed declaration to a scoped,
  *   loud refusal at apply. This restores that same fold for those three call sites.
  */

package/dist/proxmox/node-network-wire.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-network-wire.d.ts","sourceRoot":"","sources":["../../src/proxmox/node-network-wire.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,EACL,KAAK,gBAAgB,EAOtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,KAAK,UAAU,EAAoB,MAAM,sBAAsB,CAAC;AAGrF;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,WAAW,GACX,YAAY,GACZ,SAAS,GACT,OAAO,GACP,MAAM,GACN,QAAQ,GACR,KAAK,GACL,QAAQ,GACR,SAAS,GACT,MAAM,GACN,MAAM,CAAC;AAEX;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AA4DD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,mBAAmB,UAAW,gBAAgB,ylCAmBxD,CAAC;AAEJ;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,UAAW,gBAAgB,sIACmB,CAAC;AAEzE,gGAAgG;AAChG,eAAO,MAAM,cAAc,SAAU,qBAAqB,GAAG,UAAU,GAAG,SAAS,sCAC3C,CAAC;AAEzC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,OAAO,eAAgB,qBAAqB,SAAS,gBAAgB,YAcnB,CAAC"}
+{"version":3,"file":"node-network-wire.d.ts","sourceRoot":"","sources":["../../src/proxmox/node-network-wire.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,EACL,KAAK,gBAAgB,EAOtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,KAAK,UAAU,EAAoB,MAAM,sBAAsB,CAAC;AAGrF;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,WAAW,GACX,YAAY,GACZ,SAAS,GACT,OAAO,GACP,MAAM,GACN,QAAQ,GACR,KAAK,GACL,QAAQ,GACR,SAAS,GACT,MAAM,GACN,MAAM,CAAC;AAEX;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AA4DD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,mBAAmB,UAAW,gBAAgB,ylCAaxD,CAAC;AAEJ;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,aAAa,UAAW,gBAAgB,sIACmB,CAAC;AAEzE,gGAAgG;AAChG,eAAO,MAAM,cAAc,SAAU,qBAAqB,GAAG,UAAU,GAAG,SAAS,sCAC3C,CAAC;AAEzC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,OAAO,eAAgB,qBAAqB,SAAS,gBAAgB,YAcnB,CAAC"}

package/docs/upstream-conformance.md

@@ -144,9 +144,11 @@ then tidiness.
    - 42 test files on `node:test` (S43);
    - `Bao.*` type strings, where the vendor name is `OpenBao` (H14).
 
-   No distilled SDK exists. OpenBao serves an OpenAPI document, so a generated SDK in
-   distilled's shape is the S23 path. **Decision:** maintainer, on whether the kit authors
-   a distilled package.
+   The generated SDK ships as `@homeflare/distilled-openbao` (interim alias for
+   `@distilled.cloud/openbao`). `Bao.Policy` and `Bao.AuthRole` use it for CRUD and rename collision
+   reads, sharing the existing eight-request gate, timeout and agent transport. Other
+   Bao families still use the raw client. Auth/login envelope decoding and house plugin
+   schemas remain separate SDK work before those families can migrate.
 
 ## Remaining family findings
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.37.5",
+  "version": "0.37.6",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -122,9 +122,10 @@
     "@distilled.cloud/grafana": "npm:@homeflare/distilled-grafana@0.2.0",
     "@distilled.cloud/litellm": "npm:@homeflare/distilled-litellm@0.2.0",
     "@distilled.cloud/netbox": "npm:@homeflare/distilled-netbox@0.3.0",
+    "@distilled.cloud/openbao": "npm:@homeflare/distilled-openbao@0.2.2",
     "@distilled.cloud/opnsense": "npm:@homeflare/distilled-opnsense@0.2.0",
     "@distilled.cloud/paperless-ngx": "npm:@homeflare/distilled-paperless-ngx@0.3.0",
-    "@distilled.cloud/proxmox": "npm:@homeflare/distilled-proxmox@0.3.1",
+    "@distilled.cloud/proxmox": "npm:@homeflare/distilled-proxmox@0.3.2",
     "@distilled.cloud/proxmox-backup": "npm:@homeflare/distilled-proxmox-backup@0.3.1",
     "@distilled.cloud/unifi-network": "npm:@homeflare/distilled-unifi-network@0.2.0"
   },

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

@@ -1,15 +1,17 @@
 /**
  * Bao.AuthRole's secret_id TTL at the 90-day length the per-host AppRoles use.
  *
- * ★ `2160h` IS WHAT GOES ON THE WIRE, AND OPENBAO ACCEPTS IT. MEASURED 2026-09-21 with a Go probe of
+ * ★ OPENBAO ACCEPTS `2160h`. MEASURED 2026-09-21 with a Go probe of
  *   sdk v2.6.2 framework.FieldData.Validate on the approle role fields (path_role.go:166-167,
  *   TypeDurationSecond): `secret_id_ttl: "2160h"` validates and parses to 7776000 seconds. A role
  *   read hands back that integer, which attributesOf renders as `90d` — the same role.
+ * The SDK now sends the equivalent seconds directly instead of the former CLI duration string.
  * (What the diff calls a rename is pinned in rename-families.test.ts, `foldName`.)
  */
-import assert from 'node:assert/strict';
-import { describe, it } from 'node:test';
-import { type BaoAuthRoleProps, attributesOf, matches, writeBody } from './auth-role-form.ts';
+import { describe, expect, it } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { type BaoAuthRoleProps, attributesOf, matches } from './auth-role-form.ts';
+import { authRoleRequest } from './auth-role-wire.ts';
 
 const PROPS: BaoAuthRoleProps = {
   bindSecretId: true,
@@ -22,8 +24,8 @@ const PROPS: BaoAuthRoleProps = {
 };
 
 describe('auth role secret_id TTL', () => {
-  it('writes 2160h as given', () => {
-    assert.equal(writeBody(PROPS)['secret_id_ttl'], '2160h');
+  it('writes 2160h as the equivalent SDK seconds', async () => {
+    expect((await Effect.runPromise(authRoleRequest(PROPS))).secret_id_ttl).toBe(7776000);
   });
 
   it('reads 7776000 seconds back as the same role', () => {
@@ -36,8 +38,8 @@ describe('auth role secret_id TTL', () => {
       token_ttl: 900,
     };
     const attributes = attributesOf(PROPS, live);
-    assert.equal(attributes.secretIdTtl, '90d');
-    assert.equal(matches(attributes, PROPS), true);
-    assert.equal(matches(attributesOf(PROPS, { ...live, secret_id_ttl: 0 }), PROPS), false);
+    expect(attributes.secretIdTtl).toBe('90d');
+    expect(matches(attributes, PROPS)).toBe(true);
+    expect(matches(attributesOf(PROPS, { ...live, secret_id_ttl: 0 }), PROPS)).toBe(false);
   });
 });

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

@@ -70,25 +70,6 @@ export const attributesOf = (
 
 export const readPath = (name: string) => `auth/approle/role/${name}`;
 
-/**
- * The body for `PUT auth/approle/role/<name>`.
- *
- * ★ ALL STRINGS, EXACTLY THE `k=v` PAIRS `bao write` USED TO SEND — see `baoWrite` in bao-http.ts.
- */
-export const writeBody = (props: BaoAuthRoleProps): Record<string, string> => {
-  const body: Record<string, string> = {
-    token_policies: props.tokenPolicies.join(','),
-    token_ttl: props.tokenTtl,
-    token_max_ttl: props.tokenMaxTtl,
-    secret_id_ttl: props.secretIdTtl,
-  };
-  if (props.bindSecretId !== undefined) body['bind_secret_id'] = String(props.bindSecretId);
-  if (props.secretIdNumUses !== undefined) {
-    body['secret_id_num_uses'] = String(props.secretIdNumUses);
-  }
-  return body;
-};
-
 const samePolicies = (want: readonly string[], have: readonly string[]) =>
   want.length === have.length && want.every((policy, index) => policy === have[index]);
 

package/src/openbao/auth-role-identity.ts

@@ -0,0 +1,24 @@
+import { readPath } from './auth-role-form.ts';
+import { authRoleExists } from './auth-role-wire.ts';
+import { declaredString, judgeMoveWith } from './rename.ts';
+import { foldName, nameIdentity } from './rename-identity.ts';
+
+export const authRoleIdentity = nameIdentity<{ readonly name: string }>(
+  'Bao.AuthRole',
+  readPath,
+  foldName,
+);
+
+/** All occupied-name reads share the SDK's typed absence and refusal behavior. */
+export const judgeAuthRoleRename = (
+  olds: unknown,
+  news: unknown,
+  output: { readonly name: string } | undefined,
+) =>
+  judgeMoveWith(
+    'Bao.AuthRole',
+    output === undefined ? declaredString(olds, 'name') : output.name,
+    declaredString(news, 'name'),
+    authRoleExists,
+    foldName,
+  );

package/src/openbao/auth-role-sdk.test.ts

@@ -0,0 +1,155 @@
+/** AppRole metadata through the real SDK and Alchemy's upstream test harness; no real vault. */
+import { afterAll, beforeEach, expect } from 'bun:test';
+import { adopt } from 'alchemy/AdoptPolicy';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import * as Test from 'alchemy/Test/Bun';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { BaoAuthRole, BaoAuthRoleProvider } from './auth-role.ts';
+import { BaoEnv } from './bao-http.ts';
+import { type Reply, fakeBao } from './fake-bao.ts';
+import { wireRoles } from './fake-engines-roles.ts';
+import { writesOf } from './fake-stack.ts';
+
+const store = wireRoles();
+let refused: Reply | undefined;
+const bao = fakeBao((seen) =>
+  seen.method === 'GET' && refused !== undefined ? refused : store(seen),
+);
+afterAll(() => bao.stop());
+beforeEach(() => {
+  store.live.clear();
+  bao.seen.length = 0;
+  refused = undefined;
+});
+const { test } = Test.make({
+  adopt: true,
+  dev: false,
+  sidecar: false,
+  stage: 'test',
+  providers: Layer.mergeAll(
+    BaoAuthRoleProvider(),
+    FetchHttpClient.layer,
+    Layer.succeed(BaoEnv, { BAO_ADDR: bao.address }),
+  ),
+});
+const props = {
+  name: 'host-cert',
+  tokenPolicies: ['host-cert'],
+  tokenTtl: '15m',
+  tokenMaxTtl: '1h',
+  secretIdTtl: '2160h',
+};
+const path = 'auth/approle/role/host-cert';
+const existing = () =>
+  store.live.set(path, {
+    bind_secret_id: false,
+    secret_id_num_uses: 7,
+    secret_id_ttl: 7776000,
+    token_max_ttl: 3600,
+    token_policies: ['host-cert'],
+    token_ttl: 900,
+    token_period: 1800,
+    secret_id_bound_cidrs: ['192.0.2.0/24'],
+  });
+const role = (tokenTtl = '15m') => BaoAuthRole('role', { ...props, tokenTtl });
+const actions = (plan: { resources: Record<string, { action: string }> }) =>
+  Object.values(plan.resources).map((row) => row.action);
+
+test.provider('existing metadata adopts without writes, then plans and deploys noop', (scratch) =>
+  Effect.gen(function* () {
+    existing();
+    yield* scratch.deploy(role());
+    expect(writesOf(bao.seen)).toEqual([]);
+    expect(actions(yield* scratch.plan(role()))).toEqual(['noop']);
+    yield* scratch.deploy(role());
+    expect(writesOf(bao.seen)).toEqual([]);
+  }),
+);
+
+test.provider('drift writes one SDK POST and preserves omitted and unmanaged settings', (scratch) =>
+  Effect.gen(function* () {
+    existing();
+    yield* scratch.deploy(role());
+    yield* scratch.deploy(role('30m'));
+    expect(writesOf(bao.seen)).toEqual(['POST /v1/auth/approle/role/host-cert']);
+    expect(store.live.get(path)).toMatchObject({
+      bind_secret_id: false,
+      secret_id_num_uses: 7,
+      token_period: 1800,
+      token_ttl: 1800,
+      secret_id_bound_cidrs: ['192.0.2.0/24'],
+    });
+    expect(actions(yield* scratch.plan(role('30m')))).toEqual(['noop']);
+  }),
+);
+
+test.provider(
+  'typed absence creates metadata with server defaults then settles to noop',
+  (scratch) =>
+    Effect.gen(function* () {
+      yield* scratch.deploy(role());
+      expect(writesOf(bao.seen)).toEqual(['POST /v1/auth/approle/role/host-cert']);
+      expect(store.live.get(path)).toMatchObject({ bind_secret_id: true, secret_id_num_uses: 0 });
+      expect(actions(yield* scratch.plan(role()))).toEqual(['noop']);
+    }),
+);
+
+test.provider('occupied case-folded rename refuses before writes or deletes', (scratch) =>
+  Effect.gen(function* () {
+    existing();
+    yield* scratch.deploy(role().pipe(RemovalPolicy.destroy()));
+    store.live.set('auth/approle/role/taken', { ...store.live.get(path) });
+    bao.seen.length = 0;
+    const result = yield* Effect.exit(
+      scratch.plan(BaoAuthRole('role', { ...props, name: 'TAKEN' })),
+    );
+    expect(result._tag).toBe('Failure');
+    expect(writesOf(bao.seen)).toEqual([]);
+  }),
+);
+
+test.provider('existing unowned role refuses without adoption', (scratch) =>
+  Effect.gen(function* () {
+    existing();
+    expect((yield* Effect.exit(scratch.plan(role().pipe(adopt(false)))))._tag).toBe('Failure');
+    expect(writesOf(bao.seen)).toEqual([]);
+  }),
+);
+
+test.provider('destroy deletes only the recorded role and an empty redeploy is inert', (scratch) =>
+  Effect.gen(function* () {
+    yield* scratch.deploy(role().pipe(RemovalPolicy.destroy()));
+    bao.seen.length = 0;
+    yield* scratch.deploy(Effect.void);
+    expect(writesOf(bao.seen)).toEqual(['DELETE /v1/auth/approle/role/host-cert']);
+    expect(store.live.has(path)).toBe(false);
+    bao.seen.length = 0;
+    yield* scratch.deploy(Effect.void);
+    expect(writesOf(bao.seen)).toEqual([]);
+  }),
+);
+
+test.provider('default retain leaves removed role metadata untouched', (scratch) =>
+  Effect.gen(function* () {
+    yield* scratch.deploy(role());
+    bao.seen.length = 0;
+    yield* scratch.deploy(Effect.void);
+    expect(writesOf(bao.seen)).toEqual([]);
+    expect(store.live.has(path)).toBe(true);
+  }),
+);
+
+for (const status of [200, 403]) {
+  test.provider(`a malformed or denied ${status} read never becomes create or noop`, (scratch) =>
+    Effect.gen(function* () {
+      existing();
+      yield* scratch.deploy(role());
+      refused = { status, json: { data: {}, errors: ['refused'] } };
+      expect((yield* Effect.exit(scratch.plan(role())))._tag).toBe('Failure');
+      expect(writesOf(bao.seen)).toEqual([]);
+      refused = undefined;
+    }),
+  );
+}

package/src/openbao/auth-role-wire.test.ts

@@ -0,0 +1,128 @@
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { judgeAuthRoleRename } from './auth-role-identity.ts';
+import { deleteAuthRole, readAuthRole, writeAuthRole } from './auth-role-wire.ts';
+import { run, runFailure, withFake } from './fake-bao.ts';
+
+const PROPS = {
+  name: 'host-cert',
+  tokenPolicies: ['host-cert'],
+  tokenTtl: '15m',
+  tokenMaxTtl: '1h',
+  secretIdTtl: '2160h',
+};
+const DATA = {
+  bind_secret_id: true,
+  secret_id_num_uses: 0,
+  secret_id_ttl: 7776000,
+  token_max_ttl: 3600,
+  token_policies: ['host-cert'],
+  token_ttl: 900,
+};
+
+test('metadata SDK POST preserves omission/false/zero and never sends credential IDs', async () => {
+  await withFake(
+    () => ({ status: 204 }),
+    async (bao) => {
+      const env = { BAO_ADDR: bao.address, BAO_NAMESPACE: 'fixture', BAO_TOKEN: 'fake-token' };
+      await run(env, writeAuthRole(PROPS));
+      await run(env, writeAuthRole({ ...PROPS, bindSecretId: false, secretIdNumUses: 0 }));
+      expect(bao.seen.map(({ method }) => method)).toEqual(['POST', 'POST']);
+      const [first, second] = bao.seen;
+      if (first === undefined || second === undefined) throw new Error('expected both SDK writes');
+      expect(first.path).toBe('/v1/auth/approle/role/host-cert');
+      expect(first.headers.get('x-vault-request')).toBe('true');
+      expect(first.headers.get('x-vault-namespace')).toBe('fixture');
+      expect(JSON.parse(first.body)).toEqual({
+        token_policies: ['host-cert'],
+        token_ttl: 900,
+        token_max_ttl: 3600,
+        secret_id_ttl: 7776000,
+      });
+      expect(JSON.parse(second.body)).toEqual({
+        ...JSON.parse(first.body),
+        bind_secret_id: false,
+        secret_id_num_uses: 0,
+      });
+    },
+  );
+});
+
+for (const [status, tag] of [
+  [401, 'Unauthorized'],
+  [403, 'Forbidden'],
+  [500, 'InternalServerError'],
+] as const) {
+  test(`metadata SDK ${status} propagates for every verb and collision reads without retry`, async () => {
+    await withFake(
+      () => ({ status, json: { errors: ['refused'] } }),
+      async (bao) => {
+        const env = { BAO_ADDR: bao.address };
+        for (const op of [
+          Effect.asVoid(readAuthRole('host-cert')),
+          Effect.asVoid(writeAuthRole(PROPS)),
+          Effect.asVoid(deleteAuthRole('host-cert')),
+          Effect.asVoid(judgeAuthRoleRename({ name: 'old' }, { name: 'new' }, undefined)),
+        ])
+          expect(await runFailure(env, op)).toMatchObject({ _tag: tag });
+        expect(bao.seen.map(({ method }) => method)).toEqual(['GET', 'POST', 'DELETE', 'GET']);
+      },
+    );
+  });
+}
+
+test('typed missing read is absence and missing delete is success', async () => {
+  await withFake(
+    () => ({ status: 404, json: { errors: [] } }),
+    async (bao) => {
+      const env = { BAO_ADDR: bao.address };
+      expect(await run(env, readAuthRole('gone'))).toBeUndefined();
+      await run(env, deleteAuthRole('gone'));
+      expect(bao.seen).toHaveLength(2);
+    },
+  );
+});
+
+test('a malformed 200 never supplies role defaults or becomes absence', async () => {
+  for (const data of [
+    null,
+    {},
+    { ...DATA, token_policies: 'host-cert' },
+    { ...DATA, bind_secret_id: 'true' },
+    { ...DATA, token_ttl: -1 },
+  ]) {
+    await withFake(
+      () => ({ status: 200, json: { data } }),
+      async (bao) => {
+        expect(
+          String(await runFailure({ BAO_ADDR: bao.address }, readAuthRole('host-cert'))),
+        ).toContain('incomplete role metadata');
+      },
+    );
+  }
+});
+
+test('unmanaged nullable vendor fields do not prevent a valid metadata read', async () => {
+  await withFake(
+    () => ({ status: 200, json: { data: { ...DATA, secret_id_bound_cidrs: null } } }),
+    async (bao) => {
+      expect(await run({ BAO_ADDR: bao.address }, readAuthRole('host-cert'))).toMatchObject(DATA);
+    },
+  );
+});
+
+test('invalid TTL conversion refuses before any SDK exchange', async () => {
+  await withFake(
+    () => ({ status: 204 }),
+    async (bao) => {
+      for (const tokenTtl of ['invalid', '999999999999999999999999999h']) {
+        expect(
+          String(
+            await runFailure({ BAO_ADDR: bao.address }, writeAuthRole({ ...PROPS, tokenTtl })),
+          ),
+        ).toContain('invalid role TTL');
+      }
+      expect(bao.seen).toEqual([]);
+    },
+  );
+});

package/src/openbao/auth-role-wire.ts

@@ -0,0 +1,89 @@
+/**
+ * AppRole METADATA through the named SDK operations (OpenBao 2.6.2 generated schema).
+ * ★ pathRoleRead returns nil for absence; logical.RespondErrorCommon turns that read into
+ * 404. pathRoleDelete returns nil for an already absent role (204). Reasoned from v2.6.2
+ * builtin/credential/approle/path_role.go:1758-1904 and sdk/logical/response_util.go:21-26.
+ * ⛔ No role-id, secret-id or login request belongs in this configuration lifecycle.
+ */
+import {
+  type AppRoleReadRoleResponse,
+  type AppRoleWriteRoleRequest,
+  appRoleDeleteRole,
+  appRoleReadRole,
+  appRoleWriteRole,
+} from '@distilled.cloud/openbao/approle';
+import * as Effect from 'effect/Effect';
+import { type BaoAuthRoleProps, readPath } from './auth-role-form.ts';
+import { BaoError } from './bao-status.ts';
+import { runBao, runBaoRead, runBaoWrite } from './distilled.ts';
+import { parseDuration } from './mount-form.ts';
+
+const identity = (name: string) => ({ approle_mount_path: 'approle', role_name: name });
+const seconds = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+
+/**
+ * The vendor always returns these managed fields (pathRoleRead + tokenutil.PopulateTokenData).
+ * Generated response fields are optional, so a proxy's 200 {} must not supply default values.
+ * Ignore unmanaged fields: secret_id_bound_cidrs can legitimately be null in the vendor response.
+ */
+const completeRole = (live: AppRoleReadRoleResponse): boolean =>
+  live !== null &&
+  typeof live === 'object' &&
+  typeof live.bind_secret_id === 'boolean' &&
+  seconds(live.secret_id_num_uses) &&
+  seconds(live.secret_id_ttl) &&
+  seconds(live.token_ttl) &&
+  seconds(live.token_max_ttl) &&
+  Array.isArray(live.token_policies) &&
+  live.token_policies.every((policy) => typeof policy === 'string');
+
+export const readAuthRole = (name: string) =>
+  runBaoRead(appRoleReadRole(identity(name))).pipe(
+    Effect.flatMap((live) =>
+      completeRole(live)
+        ? Effect.succeed(live)
+        : Effect.fail(new BaoError(200, 'GET', readPath(name), ['incomplete role metadata'])),
+    ),
+    Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
+  );
+
+export const authRoleExists = (name: string) =>
+  readAuthRole(name).pipe(Effect.map((live) => live !== undefined));
+
+export const authRoleRequest = (props: BaoAuthRoleProps) =>
+  Effect.gen(function* () {
+    const tokenTtl = parseDuration(props.tokenTtl);
+    const tokenMaxTtl = parseDuration(props.tokenMaxTtl);
+    const secretIdTtl = parseDuration(props.secretIdTtl);
+    if (!seconds(tokenTtl) || !seconds(tokenMaxTtl) || !seconds(secretIdTtl)) {
+      return yield* Effect.fail(
+        new BaoError(0, 'POST', readPath(props.name), ['invalid role TTL duration']),
+      );
+    }
+    // ★ The former CLI-style body used strings for every k=v. The SDK schema uses seconds,
+    // booleans and arrays; omitted knobs stay omitted on update.
+    // pathRoleCreateUpdate preserves absent bind_secret_id/secret_id_num_uses on existing roles.
+    const request: AppRoleWriteRoleRequest = {
+      ...identity(props.name),
+      token_policies: [...props.tokenPolicies],
+      token_ttl: tokenTtl,
+      token_max_ttl: tokenMaxTtl,
+      secret_id_ttl: secretIdTtl,
+      ...(props.bindSecretId === undefined ? {} : { bind_secret_id: props.bindSecretId }),
+      ...(props.secretIdNumUses === undefined ? {} : { secret_id_num_uses: props.secretIdNumUses }),
+    };
+    return request;
+  });
+
+/**
+ * ★ A FULL-REPLACE WRITE, like the policy write: every managed field travels in the request
+ * every time (only genuinely omitted knobs stay omitted), so a transport failure is safe to
+ * retry through `runBaoWrite` — the replay sends the identical desired state.
+ */
+export const writeAuthRole = (props: BaoAuthRoleProps) =>
+  authRoleRequest(props).pipe(Effect.flatMap((request) => runBaoWrite(appRoleWriteRole(request))));
+
+/** Other typed SDK failures, including denied deletes, propagate unchanged. */
+export const deleteAuthRole = (name: string) =>
+  runBao(appRoleDeleteRole(identity(name))).pipe(Effect.catchTag('NotFound', () => Effect.void));

package/src/openbao/auth-role.ts

@@ -23,10 +23,10 @@ import {
   attributesOf,
   matches,
   readPath,
-  writeBody,
 } from './auth-role-form.ts';
-import { baoDelete, baoRead, baoWrite } from './bao-http.ts';
-import { foldName, guardRename, judgeRename, nameIdentity } from './rename-identity.ts';
+import { authRoleIdentity, judgeAuthRoleRename } from './auth-role-identity.ts';
+import { deleteAuthRole, readAuthRole, writeAuthRole } from './auth-role-wire.ts';
+import { guardRename } from './rename-identity.ts';
 
 export type { BaoAuthRoleAttributes, BaoAuthRoleProps };
 
@@ -48,13 +48,13 @@ export const BaoAuthRole = Resource<BaoAuthRole>('Bao.AuthRole', {
  *   :1537), so `Host` → `host` is the SAME role: a `replace` there would write it, then — under
  *   `destroy` — delete the old generation, which is that same role.
  */
-const IDENTITY = nameIdentity<BaoAuthRoleAttributes>('Bao.AuthRole', readPath, foldName);
+const IDENTITY = authRoleIdentity;
 
 const readRole = (props: BaoAuthRoleProps) =>
   Effect.gen(function* () {
-    const live = yield* baoRead(readPath(props.name));
+    const live = yield* readAuthRole(props.name);
     if (live === undefined) return undefined;
-    return attributesOf(props, live);
+    return attributesOf(props, { ...live });
   });
 
 export const BaoAuthRoleProvider = () =>
@@ -92,7 +92,7 @@ export const BaoAuthRoleProvider = () =>
            *   generation of a replace (Apply.ts:2164-2173). For per-host roles (host-approles.ts),
            *   opt into `RemovalPolicy.destroy()` or destroy the old role's accessors by hand.
            */
-          const move = yield* judgeRename(IDENTITY, olds, news, output);
+          const move = yield* judgeAuthRoleRename(olds, news, output);
           // ★ No attributes: an unfinished generation, proven ours or not by provingResumes.
           if (output === undefined) return undefined;
           if (move !== undefined) return { action: 'replace' } as const;
@@ -111,7 +111,7 @@ export const BaoAuthRoleProvider = () =>
           if (live !== undefined)
             yield* refuseTakeover({ fqn, instanceId, output }, `Bao.AuthRole ${path}`);
           if (live === undefined || !matches(live, news)) {
-            yield* baoWrite('PUT', readPath(news.name), writeBody(news));
+            yield* writeAuthRole(news);
           }
           const after = yield* readRole(news);
           if (after === undefined) {
@@ -136,7 +136,7 @@ export const BaoAuthRoleProvider = () =>
          *   because every host logging in with the role is locked out at the delete.
          */
         delete: Effect.fn(function* ({ output }) {
-          yield* baoDelete(readPath(output.name));
+          yield* deleteAuthRole(output.name);
           return undefined;
         }),
       }),