@homeflare/distilled-openbao 0.2.0 → 0.2.2

package/src/protocol-mount-tables.ts

@@ -0,0 +1,60 @@
+/**
+ * The auth/mount inventories require a data map (OpenBao v2.6.2
+ * vault/logical_system.go:930-959,2108-2134; api/v2 sys_{auth,mounts}.go).
+ * A missing envelope must never masquerade as an empty table and authorize
+ * a consumer's create. Other logical, health and login shapes are separate.
+ */
+import * as API from "@distilled.cloud/core/api";
+import { getAnn } from "@distilled.cloud/core/protocol-http";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import { OpenBaoParseError } from "./errors.ts";
+import { mountTableSymbol } from "./traits.ts";
+
+const invalidTable = () =>
+  new OpenBaoParseError({
+    body: undefined,
+    cause: "Response does not match the declared OpenBao mount table schema",
+  });
+const record = (body: unknown): body is Record<string, unknown> =>
+  typeof body === "object" && body !== null && !Array.isArray(body);
+
+export const withMountTables = (
+  base: Layer.Layer<API.Protocol>,
+): Layer.Layer<API.Protocol> =>
+  Layer.effect(
+    API.Protocol,
+    Effect.gen(function* () {
+      const protocol = yield* API.Protocol;
+      return API.Protocol.of({
+        encode: protocol.encode,
+        decode: (args) => {
+          if (
+            !getAnn(args.outputAst, mountTableSymbol) ||
+            args.response.status >= 400 ||
+            args.config.output === undefined
+          )
+            return protocol.decode(args);
+          // These schemas use wire names and contain no sensitive transforms.
+          // Validate the original envelope before core's empty-body fallback;
+          // retain unknown metadata after validation for forward compatibility.
+          // Neither body values nor schema diagnostics may enter parse errors.
+          const output = args.config.output;
+          return args.response.json.pipe(
+            Effect.mapError(invalidTable),
+            Effect.flatMap((envelope) =>
+              record(envelope) && record(envelope.data)
+                ? Schema.decodeUnknownEffect(Schema.toType(output))(
+                    envelope.data,
+                  ).pipe(
+                    Effect.as(envelope.data),
+                    Effect.mapError(invalidTable),
+                  )
+                : Effect.fail(invalidTable()),
+            ),
+          ) as Effect.Effect<unknown>;
+        },
+      });
+    }),
+  ).pipe(Layer.provide(base));

package/src/protocol-requests.test.ts

@@ -0,0 +1,66 @@
+import { expect, test } from "bun:test";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
+import { credentials } from "./credentials.ts";
+import * as Retry from "./retry.ts";
+import { policiesDeleteAclPolicy } from "./services/policies.ts";
+
+for (const token of [undefined, "", "test-token"]) {
+  test(`agent request header is present; ${token ? "nonempty" : "absent or empty"} token has correct header semantics`, async () => {
+    const client = HttpClient.make((request) => {
+      expect(request.headers["x-vault-request"]).toBe("true");
+      if (token) expect(request.headers["x-vault-token"]).toBe(token);
+      else expect(request.headers["x-vault-token"]).toBeUndefined();
+      expect(request.headers["x-vault-namespace"]).toBeUndefined();
+      return Effect.succeed(
+        HttpClientResponse.fromWeb(
+          request,
+          new Response(null, { status: 204 }),
+        ),
+      );
+    });
+    await Effect.runPromise(
+      policiesDeleteAclPolicy({ name: "test" }).pipe(
+        Retry.none,
+        Effect.provide(
+          Layer.mergeAll(
+            Layer.succeed(HttpClient.HttpClient, client),
+            credentials({ addr: "http://fake.invalid", token }),
+          ),
+        ),
+      ),
+    );
+  });
+}
+
+test("every status mapped by the protocol is represented in the operation error union", async () => {
+  // These catchTag calls must compile: core DEFAULT_ERRORS excludes both tags,
+  // but OpenBaoProtocol's default HTTP_STATUS_MAP emits them for every operation.
+  for (const status of [403, 404]) {
+    const client = HttpClient.make((request) =>
+      Effect.succeed(
+        HttpClientResponse.fromWeb(
+          request,
+          Response.json({ errors: [] }, { status }),
+        ),
+      ),
+    );
+    const tag = await Effect.runPromise(
+      policiesDeleteAclPolicy({ name: "test" }).pipe(
+        Retry.none,
+        Effect.as("success"),
+        Effect.catchTag("Forbidden", () => Effect.succeed("Forbidden")),
+        Effect.catchTag("NotFound", () => Effect.succeed("NotFound")),
+        Effect.provide(
+          Layer.mergeAll(
+            Layer.succeed(HttpClient.HttpClient, client),
+            credentials({ addr: "http://fake.invalid", token: "test-token" }),
+          ),
+        ),
+      ),
+    );
+    expect(tag).toBe(status === 403 ? "Forbidden" : "NotFound");
+  }
+});

package/src/protocol.ts

@@ -31,9 +31,11 @@
  * match on status, or on message when OpenBao actually supplies one — see
  * `patches/`.
  *
- * Authentication is a single header, `X-Vault-Token`, plus an optional
- * `X-Vault-Namespace` when the credential carries one — the estate always
- * does (`BAO_NAMESPACE=homeflare`). A namespace does not change a mounted
+ * Authentication is `X-Vault-Token` when a credential carries a nonempty
+ * token; omit it for a local agent that supplies its own identity. An
+ * optional `X-Vault-Namespace` selects a namespace; absent means root.
+ * `X-Vault-Request: true` admits agent listeners with require_request_header
+ * (OpenBao v2.6.2 command/agent.go:544-548). A namespace does not change a mounted
  * backend's own path shape (see `stacks/distilled-submodules/spec-repos/
  * openbao/fetch-specs.ts`'s module docs for how that was confirmed), so it
  * is purely a request header here, never a path segment.
@@ -51,6 +53,7 @@ import {
 } from "@distilled.cloud/core/protocol-rest";
 import { Credentials, type Config } from "./credentials.ts";
 import { UnknownOpenBaoError, type DefaultErrors } from "./errors.ts";
+import { withMountTables } from "./protocol-mount-tables.ts";
 
 /**
  * Error channel shared by every generated OpenBao operation. Generated
@@ -100,7 +103,10 @@ export const OpenBaoProtocol: Layer.Layer<API.Protocol> =
     }),
     baseUrl: (creds) => creds.apiBaseUrl,
     headers: (creds) => ({
-      "X-Vault-Token": Redacted.value(creds.token),
+      ...(creds.token && Redacted.value(creds.token) !== ""
+        ? { "X-Vault-Token": Redacted.value(creds.token) }
+        : {}),
+      "X-Vault-Request": "true",
       ...(creds.namespace ? { "X-Vault-Namespace": creds.namespace } : {}),
       Accept: "application/json",
     }),
@@ -117,4 +123,4 @@ export const OpenBaoProtocol: Layer.Layer<API.Protocol> =
         message,
         body,
       }),
-  });
+  }).pipe(withMountTables);

package/src/retry.ts

@@ -10,11 +10,10 @@
  * `packages/alchemy/src/openbao/bao-http.ts` caps in-flight OpenBao
  * exchanges at 8 process-wide (`BaoGate`, a `Semaphore`) after a real
  * outage: unbounded Alchemy fan-out took the dev listener's socket down
- * (measured 2026-09-14). That cap is `HttpClient` middleware, not a retry
- * policy, and stays exactly where it is — the kit's Effect runtime provides
- * the gated `HttpClient.HttpClient` layer underneath whichever protocol
- * (hand-rolled or this SDK) issues the request, so it keeps applying
- * unchanged to every call this package makes.
+ * (measured 2026-09-14). That cap lives inside the kit's call runner, not
+ * inside HttpClient. SDK consumers must explicitly share the same gate;
+ * merely supplying the HTTP client does not apply it. The kit runner also
+ * selects Retry.none so a failed response cannot repeat a sent write.
  *
  * @example
  * ```ts

package/src/services/auth.ts

@@ -83,9 +83,103 @@ export const AuthListEnabledMethodsRequest = /*@__PURE__*/ S.suspend(() =>
   identifier: "AuthListEnabledMethodsRequest",
 }) as any as S.Schema<AuthListEnabledMethodsRequest>;
 
-export interface AuthListEnabledMethodsResponse {}
+export type MountOptions = { [key: string]: string | undefined };
+export const MountOptions = /*@__PURE__*/ S.Record(
+  S.String,
+  S.String,
+) as any as S.Schema<MountOptions>;
+
+export type MountStrings = Array<string>;
+export const MountStrings = /*@__PURE__*/ S.Array(
+  S.String,
+) as any as S.Schema<MountStrings>;
+
+export interface MountUserLockoutConfig {
+  user_lockout_counter_reset_duration: number;
+  user_lockout_threshold: number;
+  user_lockout_duration: number;
+  user_lockout_disable: boolean;
+}
+export const MountUserLockoutConfig = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({
+    user_lockout_counter_reset_duration: S.Number,
+    user_lockout_threshold: S.Number,
+    user_lockout_duration: S.Number,
+    user_lockout_disable: S.Boolean,
+  }),
+).annotate({
+  identifier: "MountUserLockoutConfig",
+}) as any as S.Schema<MountUserLockoutConfig>;
+
+export interface MountConfig {
+  default_lease_ttl: number;
+  max_lease_ttl: number;
+  force_no_cache: boolean;
+  audit_non_hmac_request_keys?: MountStrings;
+  audit_non_hmac_response_keys?: MountStrings;
+  passthrough_request_headers?: MountStrings;
+  allowed_response_headers?: MountStrings;
+  listing_visibility?: string;
+  token_type?: string;
+  user_lockout_config?: MountUserLockoutConfig;
+}
+export const MountConfig = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({
+    default_lease_ttl: S.Number,
+    max_lease_ttl: S.Number,
+    force_no_cache: S.Boolean,
+    audit_non_hmac_request_keys: S.optional(MountStrings),
+    audit_non_hmac_response_keys: S.optional(MountStrings),
+    passthrough_request_headers: S.optional(MountStrings),
+    allowed_response_headers: S.optional(MountStrings),
+    listing_visibility: S.optional(S.String),
+    token_type: S.optional(S.String),
+    user_lockout_config: S.optional(MountUserLockoutConfig),
+  }),
+).annotate({ identifier: "MountConfig" }) as any as S.Schema<MountConfig>;
+
+export interface MountInfo {
+  type: string;
+  description: string;
+  accessor: string;
+  uuid: string;
+  plugin_version: string;
+  running_plugin_version: string;
+  running_sha256: string;
+  local: boolean;
+  seal_wrap: boolean;
+  external_entropy_access: boolean;
+  options: MountOptions | null;
+  config: MountConfig;
+  deprecation_status?: string;
+}
+export const MountInfo = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({
+    type: S.String,
+    description: S.String,
+    accessor: S.String,
+    uuid: S.String,
+    plugin_version: S.String,
+    running_plugin_version: S.String,
+    running_sha256: S.String,
+    local: S.Boolean,
+    seal_wrap: S.Boolean,
+    external_entropy_access: S.Boolean,
+    options: S.NullOr(MountOptions),
+    config: MountConfig,
+    deprecation_status: S.optional(S.String),
+  }),
+).annotate({ identifier: "MountInfo" }) as any as S.Schema<MountInfo>;
+
+export type MountTable = { [key: string]: MountInfo | undefined };
+export const MountTable = /*@__PURE__*/ S.Record(
+  S.String,
+  MountInfo,
+) as any as S.Schema<MountTable>;
+
+export type AuthListEnabledMethodsResponse = MountTable;
 export const AuthListEnabledMethodsResponse = /*@__PURE__*/ S.suspend(() =>
-  S.Struct({}),
+  MountTable.pipe(T.MountTable()),
 ).annotate({
   identifier: "AuthListEnabledMethodsResponse",
 }) as any as S.Schema<AuthListEnabledMethodsResponse>;

package/src/services/mounts.ts

@@ -83,9 +83,103 @@ export const MountsListSecretsEnginesRequest = /*@__PURE__*/ S.suspend(() =>
   identifier: "MountsListSecretsEnginesRequest",
 }) as any as S.Schema<MountsListSecretsEnginesRequest>;
 
-export interface MountsListSecretsEnginesResponse {}
+export type MountOptions = { [key: string]: string | undefined };
+export const MountOptions = /*@__PURE__*/ S.Record(
+  S.String,
+  S.String,
+) as any as S.Schema<MountOptions>;
+
+export type MountStrings = Array<string>;
+export const MountStrings = /*@__PURE__*/ S.Array(
+  S.String,
+) as any as S.Schema<MountStrings>;
+
+export interface MountUserLockoutConfig {
+  user_lockout_counter_reset_duration: number;
+  user_lockout_threshold: number;
+  user_lockout_duration: number;
+  user_lockout_disable: boolean;
+}
+export const MountUserLockoutConfig = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({
+    user_lockout_counter_reset_duration: S.Number,
+    user_lockout_threshold: S.Number,
+    user_lockout_duration: S.Number,
+    user_lockout_disable: S.Boolean,
+  }),
+).annotate({
+  identifier: "MountUserLockoutConfig",
+}) as any as S.Schema<MountUserLockoutConfig>;
+
+export interface MountConfig {
+  default_lease_ttl: number;
+  max_lease_ttl: number;
+  force_no_cache: boolean;
+  audit_non_hmac_request_keys?: MountStrings;
+  audit_non_hmac_response_keys?: MountStrings;
+  passthrough_request_headers?: MountStrings;
+  allowed_response_headers?: MountStrings;
+  listing_visibility?: string;
+  token_type?: string;
+  user_lockout_config?: MountUserLockoutConfig;
+}
+export const MountConfig = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({
+    default_lease_ttl: S.Number,
+    max_lease_ttl: S.Number,
+    force_no_cache: S.Boolean,
+    audit_non_hmac_request_keys: S.optional(MountStrings),
+    audit_non_hmac_response_keys: S.optional(MountStrings),
+    passthrough_request_headers: S.optional(MountStrings),
+    allowed_response_headers: S.optional(MountStrings),
+    listing_visibility: S.optional(S.String),
+    token_type: S.optional(S.String),
+    user_lockout_config: S.optional(MountUserLockoutConfig),
+  }),
+).annotate({ identifier: "MountConfig" }) as any as S.Schema<MountConfig>;
+
+export interface MountInfo {
+  type: string;
+  description: string;
+  accessor: string;
+  uuid: string;
+  plugin_version: string;
+  running_plugin_version: string;
+  running_sha256: string;
+  local: boolean;
+  seal_wrap: boolean;
+  external_entropy_access: boolean;
+  options: MountOptions | null;
+  config: MountConfig;
+  deprecation_status?: string;
+}
+export const MountInfo = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({
+    type: S.String,
+    description: S.String,
+    accessor: S.String,
+    uuid: S.String,
+    plugin_version: S.String,
+    running_plugin_version: S.String,
+    running_sha256: S.String,
+    local: S.Boolean,
+    seal_wrap: S.Boolean,
+    external_entropy_access: S.Boolean,
+    options: S.NullOr(MountOptions),
+    config: MountConfig,
+    deprecation_status: S.optional(S.String),
+  }),
+).annotate({ identifier: "MountInfo" }) as any as S.Schema<MountInfo>;
+
+export type MountTable = { [key: string]: MountInfo | undefined };
+export const MountTable = /*@__PURE__*/ S.Record(
+  S.String,
+  MountInfo,
+) as any as S.Schema<MountTable>;
+
+export type MountsListSecretsEnginesResponse = MountTable;
 export const MountsListSecretsEnginesResponse = /*@__PURE__*/ S.suspend(() =>
-  S.Struct({}),
+  MountTable.pipe(T.MountTable()),
 ).annotate({
   identifier: "MountsListSecretsEnginesResponse",
 }) as any as S.Schema<MountsListSecretsEnginesResponse>;

package/src/traits.ts

@@ -4,8 +4,16 @@
  * Re-exports the generic protocol traits from core so generated operations
  * import everything from one place. OpenBao speaks plain token-REST JSON
  * with a `data`-enveloped success body (unwrapped in `protocol.ts`), so
- * there are no provider-specific traits.
+ * MountTable marks the two inventory responses whose data is a path-keyed map.
  */
+import { makeAnnotation } from "@distilled.cloud/core/trait";
+
+export const mountTableSymbol = Symbol.for(
+  "@distilled.cloud/openbao/mount-table",
+);
+/** A typed dynamic map inside a required logical-response data envelope. */
+export const MountTable = () => makeAnnotation(mountTableSymbol, true);
+
 export {
   Body,
   Header,