@homeflare/distilled-openbao 0.2.0

package/src/protocol.ts

@@ -0,0 +1,120 @@
+/**
+ * OpenBaoProtocol — the shared bearer-REST protocol instantiated for
+ * OpenBao.
+ *
+ * OpenBao wraps every "logical" response (the vast majority — reads,
+ * mount/auth/role CRUD) in an envelope: `{ request_id, lease_id,
+ * renewable, lease_duration, data: {...}, wrap_info, warnings, auth }`.
+ * The generated response schemas describe the INNER `data` shape only — the
+ * OpenAPI document OpenBao's own generator produces documents just that
+ * (measured against `.generated-specs/policies.json`'s
+ * `PoliciesReadAclPolicyResponse`, which has no `request_id`/`lease_id`/etc
+ * member at all) — so `transformResponse` below unwraps `data` before
+ * decoding, exactly the rule the kit's hand-rolled client already applies
+ * (`packages/alchemy/src/openbao/bao-http.ts`'s `baoRead`: take `data` when
+ * it is an object, the whole body otherwise). A handful of endpoints are
+ * NOT logical responses and have no `data` envelope at all — `sys/health`,
+ * `sys/seal-status`, `sys/leader` answer their fields at the top level — so
+ * the unwrap only fires when `data` is actually present and an object,
+ * which leaves those untouched.
+ *
+ * ⚠️ NOT YET HANDLED: auth/login responses (`auth/<mount>/login`, and every
+ * `*-login` operation) wrap their payload under `auth`, not `data` — this
+ * protocol does not unwrap that shape yet. No migrated family calls a login
+ * endpoint through this SDK today; add an `auth`-aware unwrap (or a
+ * dedicated response trait) before one does.
+ *
+ * Failures carry `{"errors": [...]}` — zero or more strings, and often
+ * literally empty (measured 2026-09-24: OpenBao 2.6.2 answers a missing ACL
+ * policy read with `404 {"errors":[]}`, no text). There is normally no
+ * machine-readable code, so typed errors beyond the status-derived ones
+ * 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
+ * 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.
+ */
+import * as Effect from "effect/Effect";
+import type * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import type * as HttpClientError from "effect/unstable/http/HttpClientError";
+import type * as API from "@distilled.cloud/core/api";
+import type { ConfigError } from "@distilled.cloud/core/errors";
+import {
+  makeRestProtocol,
+  type RestErrorEnvelope,
+} from "@distilled.cloud/core/protocol-rest";
+import { Credentials, type Config } from "./credentials.ts";
+import { UnknownOpenBaoError, type DefaultErrors } from "./errors.ts";
+
+/**
+ * Error channel shared by every generated OpenBao operation. Generated
+ * service files annotate operations with `API.OperationMethod<I, O,
+ * OpenBaoOpError, OpenBaoOpContext>` explicitly so the compiler never infers
+ * these back out of the schema generics.
+ */
+export type OpenBaoOpError =
+  | DefaultErrors
+  | ConfigError
+  | HttpClientError.HttpClientError;
+
+/** Context (requirements) shared by every generated OpenBao operation. */
+export type OpenBaoOpContext = Credentials | HttpClient.HttpClient;
+
+/**
+ * OpenBao error bodies are `{"errors": [...]}`. Several strings are joined
+ * (`"; "`) rather than only the first kept, so a matcher's `includes` still
+ * sees text further down the list; an empty array (the common 404 shape)
+ * yields no `message`, and the protocol's own `HTTP <status>` fallback
+ * covers it. A response that arrives without that envelope (a proxy 502, an
+ * HTML error page) falls through to the same fallback.
+ */
+const errorEnvelope = (body: unknown): RestErrorEnvelope | undefined => {
+  if (body === null || typeof body !== "object") return undefined;
+  const b = body as Record<string, unknown>;
+  if (!Array.isArray(b.errors)) return undefined;
+  const messages = b.errors.filter((e): e is string => typeof e === "string");
+  return { message: messages.length > 0 ? messages.join("; ") : undefined };
+};
+
+/** Unwrap the `data` envelope — see this file's module docs. */
+const transformResponse = (body: unknown): unknown => {
+  if (body === null || typeof body !== "object") return body;
+  const data = (body as Record<string, unknown>).data;
+  return typeof data === "object" && data !== null ? data : body;
+};
+
+export const OpenBaoProtocol: Layer.Layer<API.Protocol> =
+  makeRestProtocol<Config>({
+    // Resolved on the CALLING fiber per request (the layer is memoized per
+    // process); the Credentials service holds an effect, so a token rotated
+    // between calls is picked up without rebuilding the layer.
+    credentials: Effect.gen(function* () {
+      const resolve = yield* Credentials;
+      return yield* resolve;
+    }),
+    baseUrl: (creds) => creds.apiBaseUrl,
+    headers: (creds) => ({
+      "X-Vault-Token": Redacted.value(creds.token),
+      ...(creds.namespace ? { "X-Vault-Namespace": creds.namespace } : {}),
+      Accept: "application/json",
+    }),
+    errorEnvelope,
+    transformResponse,
+    unknownError: ({ code, message, body }) =>
+      new UnknownOpenBaoError({
+        code:
+          typeof code === "string"
+            ? code
+            : code !== undefined
+              ? String(code)
+              : undefined,
+        message,
+        body,
+      }),
+  });

package/src/retry.ts

@@ -0,0 +1,84 @@
+/**
+ * OpenBao retry surface — a veneer over `@distilled.cloud/core/retry`.
+ *
+ * The `Retry` service tag is threaded into every generated operation via
+ * `API.make({ retry: Retry })`, so a caller-installed policy applies to all
+ * OpenBao calls below it and core's `makeDefault` is the fallback when none
+ * is provided.
+ *
+ * ⚠️ THIS IS NOT THE ESTATE'S CONCURRENCY GATE. The kit's own
+ * `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.
+ *
+ * @example
+ * ```ts
+ * import * as OpenBao from "@distilled.cloud/openbao";
+ *
+ * myEffect.pipe(OpenBao.Retry.transient);
+ * ```
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Retries from "@distilled.cloud/core/retry";
+
+export type Options = Retries.Options;
+export type Factory = Retries.Factory;
+export type Policy = Retries.Policy;
+
+/** Context tag for configuring retry behavior of OpenBao API calls. */
+export class Retry extends Context.Service<Retry, Policy>()("OpenBaoRetry") {}
+
+/** Provides a custom retry policy to every OpenBao API call below it. */
+export const policy: {
+  (
+    options: Options,
+  ): <A, E, R>(
+    effect: Effect.Effect<A, E, R>,
+  ) => Effect.Effect<A, E, Exclude<R, Retry>>;
+  (
+    factory: Factory,
+  ): <A, E, R>(
+    effect: Effect.Effect<A, E, R>,
+  ) => Effect.Effect<A, E, Exclude<R, Retry>>;
+} = (optionsOrFactory: Options | Factory) =>
+  Effect.provide(Layer.succeed(Retry, optionsOrFactory));
+
+/** Disables all automatic retries. */
+export const none: <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+) => Effect.Effect<A, E, Exclude<R, Retry>> = Effect.provide(
+  Layer.succeed(Retry, { while: () => false }),
+);
+
+/**
+ * The default retry policy (core's): transient/throttling/retryable errors,
+ * capped exponential backoff with jitter, server `retryAfter` hints honored
+ * with precedence.
+ */
+export const makeDefault: Factory = Retries.makeDefault;
+
+export const jittered = Retries.jittered;
+export const capped = Retries.capped;
+
+/** Retry options that retry all throttling errors indefinitely. */
+export const throttlingOptions: Options = Retries.throttlingOptions;
+
+/** Retries all throttling errors indefinitely (honoring server hints). */
+export const throttling: <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+) => Effect.Effect<A, E, Exclude<R, Retry>> = policy(Retries.throttlingFactory);
+
+/** Retry options that retry all transient errors indefinitely. */
+export const transientOptions: Options = Retries.transientOptions;
+
+/** Retries all transient errors indefinitely (honoring server hints). */
+export const transient: <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+) => Effect.Effect<A, E, Exclude<R, Retry>> = policy(Retries.transientFactory);

package/src/services/alias.ts

@@ -0,0 +1,208 @@
+// AUTO-GENERATED by scripts/generate.ts from .generated-specs (specs/spec-mirror-openbao, generated — see fetch-specs.ts). Do not edit.
+import * as S from "@distilled.cloud/core/schema";
+import * as API from "@distilled.cloud/core/api";
+import * as T from "../traits.ts";
+import {
+  OpenBaoProtocol,
+  type OpenBaoOpError,
+  type OpenBaoOpContext,
+} from "../protocol.ts";
+import * as Retry from "../retry.ts";
+
+export type { OpenBaoOpError, OpenBaoOpContext };
+
+export interface AliasDeleteByIdRequest {
+  /** ID of the alias */
+  id: string;
+}
+export const AliasDeleteByIdRequest = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({
+    id: S.String.pipe(T.Label()),
+  }).pipe(
+    T.Http({ method: "DELETE", uri: "/identity/alias/id/{id}", code: 200 }),
+  ),
+).annotate({
+  identifier: "AliasDeleteByIdRequest",
+}) as any as S.Schema<AliasDeleteByIdRequest>;
+
+export interface AliasDeleteByIdResponse {}
+export const AliasDeleteByIdResponse = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({}),
+).annotate({
+  identifier: "AliasDeleteByIdResponse",
+}) as any as S.Schema<AliasDeleteByIdResponse>;
+
+export type AliasListByIdRequestList = "true";
+export const AliasListByIdRequestList = S.String;
+
+export interface AliasListByIdRequest {
+  /** Must be set to `true` */
+  list: AliasListByIdRequestList | (string & {});
+}
+export const AliasListByIdRequest = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({
+    list: AliasListByIdRequestList.pipe(T.Query()),
+  }).pipe(T.Http({ method: "GET", uri: "/identity/alias/id", code: 200 })),
+).annotate({
+  identifier: "AliasListByIdRequest",
+}) as any as S.Schema<AliasListByIdRequest>;
+
+export interface AliasListByIdResponse {}
+export const AliasListByIdResponse = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({}),
+).annotate({
+  identifier: "AliasListByIdResponse",
+}) as any as S.Schema<AliasListByIdResponse>;
+
+export interface AliasReadByIdRequest {
+  /** ID of the alias */
+  id: string;
+}
+export const AliasReadByIdRequest = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({
+    id: S.String.pipe(T.Label()),
+  }).pipe(T.Http({ method: "GET", uri: "/identity/alias/id/{id}", code: 200 })),
+).annotate({
+  identifier: "AliasReadByIdRequest",
+}) as any as S.Schema<AliasReadByIdRequest>;
+
+export interface AliasReadByIdResponse {}
+export const AliasReadByIdResponse = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({}),
+).annotate({
+  identifier: "AliasReadByIdResponse",
+}) as any as S.Schema<AliasReadByIdResponse>;
+
+export interface AliasUpdateByIdRequest {
+  /** ID of the alias */
+  id: string;
+  /** Entity ID to which this alias should be tied to */
+  canonical_id?: string;
+  /** Entity ID to which this alias should be tied to. This field is deprecated in favor of 'canonical_id'. */
+  entity_id?: string;
+  /** Mount accessor to which this alias belongs to */
+  mount_accessor?: string;
+  /** Name of the alias */
+  name?: string;
+}
+export const AliasUpdateByIdRequest = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({
+    id: S.String.pipe(T.Label()),
+    canonical_id: S.optional(S.String),
+    entity_id: S.optional(S.String),
+    mount_accessor: S.optional(S.String),
+    name: S.optional(S.String),
+  }).pipe(
+    T.Http({ method: "POST", uri: "/identity/alias/id/{id}", code: 200 }),
+  ),
+).annotate({
+  identifier: "AliasUpdateByIdRequest",
+}) as any as S.Schema<AliasUpdateByIdRequest>;
+
+export interface AliasUpdateByIdResponse {}
+export const AliasUpdateByIdResponse = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({}),
+).annotate({
+  identifier: "AliasUpdateByIdResponse",
+}) as any as S.Schema<AliasUpdateByIdResponse>;
+
+export interface CreateAliasRequest {
+  /** Entity ID to which this alias belongs to */
+  canonical_id?: string;
+  /** Entity ID to which this alias belongs to. This field is deprecated in favor of 'canonical_id'. */
+  entity_id?: string;
+  /** ID of the alias */
+  id?: string;
+  /** Mount accessor to which this alias belongs to */
+  mount_accessor?: string;
+  /** Name of the alias */
+  name?: string;
+}
+export const CreateAliasRequest = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({
+    canonical_id: S.optional(S.String),
+    entity_id: S.optional(S.String),
+    id: S.optional(S.String),
+    mount_accessor: S.optional(S.String),
+    name: S.optional(S.String),
+  }).pipe(T.Http({ method: "POST", uri: "/identity/alias", code: 200 })),
+).annotate({
+  identifier: "CreateAliasRequest",
+}) as any as S.Schema<CreateAliasRequest>;
+
+export interface CreateAliasResponse {}
+export const CreateAliasResponse = /*@__PURE__*/ S.suspend(() =>
+  S.Struct({}),
+).annotate({
+  identifier: "CreateAliasResponse",
+}) as any as S.Schema<CreateAliasResponse>;
+
+export type AliasDeleteByIdError = OpenBaoOpError;
+export const aliasDeleteById: API.OperationMethod<
+  AliasDeleteByIdRequest,
+  AliasDeleteByIdResponse,
+  AliasDeleteByIdError,
+  OpenBaoOpContext
+> = /*@__PURE__*/ API.make(() => ({
+  input: AliasDeleteByIdRequest,
+  output: AliasDeleteByIdResponse,
+  errors: [],
+  protocol: OpenBaoProtocol,
+  retry: Retry.Retry,
+}));
+
+export type AliasListByIdError = OpenBaoOpError;
+export const aliasListById: API.OperationMethod<
+  AliasListByIdRequest,
+  AliasListByIdResponse,
+  AliasListByIdError,
+  OpenBaoOpContext
+> = /*@__PURE__*/ API.make(() => ({
+  input: AliasListByIdRequest,
+  output: AliasListByIdResponse,
+  errors: [],
+  protocol: OpenBaoProtocol,
+  retry: Retry.Retry,
+}));
+
+export type AliasReadByIdError = OpenBaoOpError;
+export const aliasReadById: API.OperationMethod<
+  AliasReadByIdRequest,
+  AliasReadByIdResponse,
+  AliasReadByIdError,
+  OpenBaoOpContext
+> = /*@__PURE__*/ API.make(() => ({
+  input: AliasReadByIdRequest,
+  output: AliasReadByIdResponse,
+  errors: [],
+  protocol: OpenBaoProtocol,
+  retry: Retry.Retry,
+}));
+
+export type AliasUpdateByIdError = OpenBaoOpError;
+export const aliasUpdateById: API.OperationMethod<
+  AliasUpdateByIdRequest,
+  AliasUpdateByIdResponse,
+  AliasUpdateByIdError,
+  OpenBaoOpContext
+> = /*@__PURE__*/ API.make(() => ({
+  input: AliasUpdateByIdRequest,
+  output: AliasUpdateByIdResponse,
+  errors: [],
+  protocol: OpenBaoProtocol,
+  retry: Retry.Retry,
+}));
+
+export type CreateAliasError = OpenBaoOpError;
+export const createAlias: API.OperationMethod<
+  CreateAliasRequest,
+  CreateAliasResponse,
+  CreateAliasError,
+  OpenBaoOpContext
+> = /*@__PURE__*/ API.make(() => ({
+  input: CreateAliasRequest,
+  output: CreateAliasResponse,
+  errors: [],
+  protocol: OpenBaoProtocol,
+  retry: Retry.Retry,
+}));