@homeflare/alchemy 0.4.1 → 0.6.0

package/src/openbao/mfa-enforcement-form.ts

@@ -0,0 +1,147 @@
+/**
+ * The form half of Bao.MfaLoginEnforcement — `identity/mfa/login-enforcement/<name>`: which logins
+ * must pass which MFA methods.
+ *
+ * ★ READ FROM openbao v2.6.2 vault/identity/mfa.go handleMFALoginEnforcementUpdate (:511-646):
+ *   · `mfa_method_ids` is required, and each id must exist in this namespace or a parent.
+ *   · The four target lists are each `GetOk`: an omitted list KEEPS its stored value, and ANY list
+ *     that is present — even empty — satisfies "one of … must be specified" (:634-636). So every
+ *     list is sent on every write (a stale target is cleared), and "all four empty" — which the
+ *     server would accept, and which enforces NOTHING — is refused here.
+ *   · Every field is a TypeStringSlice (store.go:751-772). ⚠️ A comma string there is ONE element
+ *     (sdk framework/field_data.go:343-356 WeakDecodes a string into a one-item slice), so lists
+ *     go over as JSON arrays.
+ * ⚠️ A TYPE TARGET IS BROAD. `authMethodTypes: ['jwt']` matches EVERY jwt-type mount — including a
+ *   GitHub Actions or Kubernetes issuer mount, whose logins cannot answer a TOTP prompt. Target
+ *   mounts by path (resolved to accessors) or by identity group instead.
+ */
+import { sha256 } from './digest.ts';
+import { mountPath } from './mount-form.ts';
+
+export interface BaoMfaLoginEnforcementProps {
+  /** Enforcement name, unique per namespace. */
+  name: string;
+  /** Method ids — typically `[totp.methodId]`. Any ONE listed method passing is enough. */
+  mfaMethodIds: readonly string[];
+  /**
+   * Auth mount PATHS (`oidc`, `jwt`), resolved to their accessors at plan and deploy time.
+   * ⚠️ A plain string makes no graph edge. When the mount is a BaoAuthMethod in the same stack, pass
+   *   its output (`[oidc.path]`) so it exists before this resolves — otherwise the deploy can reach
+   *   this first and refuse with "no auth mount at …".
+   */
+  authMethodPaths?: readonly string[];
+  /** Raw accessors (`auth_jwt_…`), for a mount outside this stack. */
+  authMethodAccessors?: readonly string[];
+  /** Auth mount TYPES — read the ⚠️ above first. */
+  authMethodTypes?: readonly string[];
+  /** Identity group ids whose members must pass MFA, on any mount. */
+  identityGroupIds?: readonly string[];
+  /** Identity entity ids, likewise. */
+  identityEntityIds?: readonly string[];
+}
+
+/** The live shape, and the declared one once paths are resolved to accessors. */
+export interface BaoMfaEnforcementCanonical {
+  authMethodAccessors: readonly string[];
+  authMethodTypes: readonly string[];
+  identityEntityIds: readonly string[];
+  identityGroupIds: readonly string[];
+  mfaMethodIds: readonly string[];
+}
+
+/** ⛔ No secret — ids, accessors and names. */
+export interface BaoMfaLoginEnforcementAttributes extends BaoMfaEnforcementCanonical {
+  name: string;
+  /** The server-made id. */
+  enforcementId: string;
+  namespacePath: string;
+  digest: string;
+}
+
+const sortedSet = (values: readonly string[]) =>
+  [...new Set(values.map((value) => value.trim()))].filter((value) => value !== '').sort();
+const strings = (value: unknown): readonly string[] =>
+  Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [];
+const text = (value: unknown) => (typeof value === 'string' ? value : '');
+
+const canonical = (input: BaoMfaEnforcementCanonical): BaoMfaEnforcementCanonical => ({
+  authMethodAccessors: sortedSet(input.authMethodAccessors),
+  authMethodTypes: sortedSet(input.authMethodTypes),
+  identityEntityIds: sortedSet(input.identityEntityIds),
+  identityGroupIds: sortedSet(input.identityGroupIds),
+  mfaMethodIds: sortedSet(input.mfaMethodIds),
+});
+
+/** The declaration, with `authMethodPaths` already resolved into `resolved` accessors. */
+export const canonicalFromProps = (
+  props: BaoMfaLoginEnforcementProps,
+  resolved: readonly string[],
+): BaoMfaEnforcementCanonical =>
+  canonical({
+    authMethodAccessors: [...(props.authMethodAccessors ?? []), ...resolved],
+    authMethodTypes: props.authMethodTypes ?? [],
+    identityEntityIds: props.identityEntityIds ?? [],
+    identityGroupIds: props.identityGroupIds ?? [],
+    mfaMethodIds: props.mfaMethodIds,
+  });
+
+export const canonicalFromLive = (live: Record<string, unknown>): BaoMfaEnforcementCanonical =>
+  canonical({
+    authMethodAccessors: strings(live['auth_method_accessors']),
+    authMethodTypes: strings(live['auth_method_types']),
+    identityEntityIds: strings(live['identity_entity_ids']),
+    identityGroupIds: strings(live['identity_group_ids']),
+    mfaMethodIds: strings(live['mfa_method_ids']),
+  });
+
+export const attributesOf = (
+  name: string,
+  live: Record<string, unknown>,
+): BaoMfaLoginEnforcementAttributes => {
+  const form = canonicalFromLive(live);
+  return {
+    ...form,
+    digest: sha256(JSON.stringify(form)),
+    enforcementId: text(live['id']),
+    name,
+    namespacePath: text(live['namespace_path']),
+  };
+};
+
+export const matches = (
+  attributes: BaoMfaLoginEnforcementAttributes,
+  props: BaoMfaLoginEnforcementProps,
+  resolved: readonly string[],
+): boolean => attributes.digest === sha256(JSON.stringify(canonicalFromProps(props, resolved)));
+
+/** Every list, as a JSON array, every time — the ⚠️ on GetOk above. */
+export const writeBody = (form: BaoMfaEnforcementCanonical): Record<string, unknown> => ({
+  auth_method_accessors: [...form.authMethodAccessors],
+  auth_method_types: [...form.authMethodTypes],
+  identity_entity_ids: [...form.identityEntityIds],
+  identity_group_ids: [...form.identityGroupIds],
+  mfa_method_ids: [...form.mfaMethodIds],
+});
+
+const NAME = /^\w(?:[\w.-]*\w)?$/;
+
+export const problems = (
+  props: BaoMfaLoginEnforcementProps,
+  missingPaths: readonly string[],
+): readonly string[] => {
+  const found: string[] = [];
+  if (!NAME.test(props.name)) found.push(`name \`${props.name}\` is not a valid enforcement name`);
+  if (sortedSet(props.mfaMethodIds).length === 0) found.push('mfaMethodIds is empty');
+  const targets = [
+    props.authMethodPaths,
+    props.authMethodAccessors,
+    props.authMethodTypes,
+    props.identityGroupIds,
+    props.identityEntityIds,
+  ].some((list) => sortedSet(list ?? []).length > 0);
+  if (!targets) found.push('no target: an enforcement with none is accepted and enforces NOTHING');
+  if (missingPaths.length > 0) {
+    found.push(`no auth mount at ${missingPaths.map((path) => mountPath(path)).join(', ')}`);
+  }
+  return found;
+};

package/src/openbao/mfa-enforcement.ts

@@ -0,0 +1,143 @@
+/**
+ * A login-MFA enforcement — `identity/mfa/login-enforcement/<name>`: logins through these mounts
+ * (or by these groups/entities) must also pass one of these MFA methods. The machine-access plan's
+ * "admin requires OpenBao login MFA" is this resource.
+ *
+ * ⛔ ENROL BEFORE YOU ENFORCE. A login the enforcement matches, by an entity with no secret for any
+ *   listed method, FAILS (login_mfa.go validateLoginMFAInternal: "MFA secret … not present"). Enrol
+ *   every admin (`identity/mfa/method/totp/admin-generate`, which RETURNS the secret — never through
+ *   Alchemy) before the first deploy of this, or the admin lane locks itself out.
+ * ⚠️ IT MATCHES MOUNTS, GROUPS AND ENTITIES — NEVER ROLES. An enforcement on the `jwt/` accessor
+ *   covers every role on that mount (login_mfa.go buildMFAEnforcementConfigList :932-1017). To put
+ *   MFA on admin only, give admin its own auth mount, or target an identity group of admins.
+ * ⛔ THE DELETE IS REFUSED: IN 2.6.2 IT DOES NOT STICK. DeleteMFALoginEnforcementConfigByNameAndNamespace
+ *   (login_mfa.go:1879-1902) removes the entry from memory and never from storage, so it RETURNS on the
+ *   next unseal — tracked upstream as openbao/openbao#4030, open on 2026-09-21. Worse, a method
+ *   deleted in between leaves the resurrected enforcement naming an id that no longer exists, and
+ *   every login it matches then fails ("MFA method configuration not present", :871-877). A delete
+ *   that reports success and quietly comes back is the lie this package refuses to tell. Under the
+ *   default `retain` it never runs; with `destroy`, set `retain` to drop it from state and leave it
+ *   live — which is what the server would do anyway.
+ *
+ * ★ REPLACE SEMANTICS (REPLACE.md): `name` changed → `replace`, create-first (names are per
+ *   namespace; the new one cannot collide). Under `retain` BOTH enforcements then apply — fail
+ *   closed. Under `destroy` the old one's delete is refused, so the deploy stops after creating.
+ */
+import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import type { BaoError } from './bao-status.ts';
+import {
+  type BaoMfaLoginEnforcementAttributes,
+  type BaoMfaLoginEnforcementProps,
+  attributesOf,
+  canonicalFromProps,
+  matches,
+  problems,
+  writeBody,
+} from './mfa-enforcement-form.ts';
+import { authAccessors, readEnforcement, writeEnforcement } from './mfa-wire.ts';
+
+export type {
+  BaoMfaLoginEnforcementAttributes,
+  BaoMfaLoginEnforcementProps,
+} from './mfa-enforcement-form.ts';
+
+export interface BaoMfaLoginEnforcement extends Resource<
+  'Bao.MfaLoginEnforcement',
+  BaoMfaLoginEnforcementProps,
+  BaoMfaLoginEnforcementAttributes,
+  never,
+  HttpClient.HttpClient
+> {}
+
+export const BaoMfaLoginEnforcement = Resource<BaoMfaLoginEnforcement>('Bao.MfaLoginEnforcement', {
+  defaultRemovalPolicy: 'retain',
+});
+
+type Env = HttpClient.HttpClient;
+
+const refuse = (name: string, message: string): Effect.Effect<never> =>
+  Effect.die(new Error(`Bao.MfaLoginEnforcement ${name}: ${message}`));
+
+/** Paths resolved to accessors, and what the declaration would be refused for. */
+const resolveTargets = (props: BaoMfaLoginEnforcementProps) =>
+  Effect.map(authAccessors(props.authMethodPaths ?? []), ({ accessors, missing }) => ({
+    bad: problems(props, missing),
+    resolved: accessors,
+  }));
+
+const readLive = (
+  name: string,
+): Effect.Effect<BaoMfaLoginEnforcementAttributes | undefined, BaoError, Env> =>
+  Effect.map(readEnforcement(name), (live) =>
+    live === undefined ? undefined : attributesOf(name, live),
+  );
+
+export const planEnforcement = (
+  props: BaoMfaLoginEnforcementProps,
+): Effect.Effect<'noop' | 'update', BaoError, Env> =>
+  Effect.gen(function* () {
+    const { bad, resolved } = yield* resolveTargets(props);
+    if (bad.length > 0) return 'update';
+    const live = yield* readLive(props.name);
+    return live !== undefined && matches(live, props, resolved) ? 'noop' : 'update';
+  });
+
+/** Write when live differs, then prove it by reading back. */
+export const reconcileEnforcement = (
+  props: BaoMfaLoginEnforcementProps,
+): Effect.Effect<BaoMfaLoginEnforcementAttributes, BaoError, Env> =>
+  Effect.gen(function* () {
+    const { bad, resolved } = yield* resolveTargets(props);
+    if (bad.length > 0) return yield* refuse(props.name, bad.join('; '));
+    const live = yield* readLive(props.name);
+    if (live === undefined || !matches(live, props, resolved)) {
+      yield* writeEnforcement(props.name, writeBody(canonicalFromProps(props, resolved)));
+    }
+    const after = yield* readLive(props.name);
+    if (after === undefined)
+      return yield* refuse(props.name, 'the write succeeded but it is absent.');
+    if (!matches(after, props, resolved)) {
+      return yield* refuse(props.name, 'the enforcement read back different.');
+    }
+    return after;
+  });
+
+export const BaoMfaLoginEnforcementProvider = () =>
+  Provider.effect(
+    BaoMfaLoginEnforcement,
+    Effect.succeed(
+      BaoMfaLoginEnforcement.Provider.of({
+        /** ⛔ The namespace's enforcement listing is not a list of things this owns. */
+        list: () => Effect.succeed([]),
+
+        read: Effect.fn(function* ({ olds }) {
+          return yield* readLive(olds.name);
+        }),
+
+        /** ⛔ IT COMPARES THE LIVE ENFORCEMENT — a target removed by hand is drift, not a noop. */
+        diff: Effect.fn(function* ({ news, output }) {
+          if (output === undefined || !isResolved(news)) return undefined;
+          if (news.name !== output.name) return { action: 'replace' } as const;
+          return { action: yield* planEnforcement(news) } as const;
+        }),
+
+        reconcile: Effect.fn(function* ({ news }) {
+          return yield* reconcileEnforcement(news);
+        }),
+
+        /** ⛔ REFUSED — read the header: in 2.6.2 the delete does not survive a restart. */
+        delete: Effect.fn(function* ({ output }) {
+          return yield* refuse(
+            output.name,
+            'REFUSING to delete: OpenBao 2.6.2 drops a login enforcement from memory only, and it ' +
+              'returns on the next unseal (openbao/openbao#4030). Set this resource back to ' +
+              'retain to drop it from state; remove it for good only once the server is fixed.',
+          );
+        }),
+      }),
+    ),
+  );

package/src/openbao/mfa-totp-form.ts

@@ -0,0 +1,155 @@
+/**
+ * The form half of Bao.MfaTotpMethod — a TOTP login-MFA method, identified by its `method_name`.
+ *
+ * ★ READ FROM openbao v2.6.2 vault/identity/store.go:349-427 (fields) and vault/identity/mfa.go
+ *   parseTOTPConfig (:662-741): `issuer` is required; `algorithm` is SHA1|SHA256|SHA512; `digits`
+ *   6|8; `skew` 0|1; `period`, `key_size` above zero; `max_validation_attempts` 0 means the default
+ *   of 5 (:35). EVERY field is `d.Get`, so a write resets whatever it omits — every one is sent.
+ * ★ THE READ (login_mfa.go mfaConfigToMap :775-829) answers `period` in seconds and `algorithm` as
+ *   its name; `name`, `id` and `namespace_path` ride along.
+ * ⚠️ A CHANGED ALGORITHM, DIGITS OR PERIOD APPLIES TO NEW ENROLMENTS ONLY. Validation uses the
+ *   parameters stored with each entity's own secret (login_mfa.go validateTOTP :1520-1545), so an
+ *   enrolled admin keeps working — with the old parameters — until re-enrolled.
+ * ⛔ NO SECRET: the method holds no key. Each entity's TOTP secret is generated per entity by
+ *   `.../totp/generate` or `admin-generate`, which RETURNS it; this resource calls neither.
+ */
+import { sha256 } from './digest.ts';
+import { parseDuration, ttlSeconds } from './mount-form.ts';
+
+export type BaoTotpAlgorithm = 'SHA1' | 'SHA256' | 'SHA512';
+
+export interface BaoMfaTotpMethodProps {
+  /** `method_name` — the declarative key, unique per namespace. ⛔ A rename is refused (mfa-totp.ts). */
+  name: string;
+  /** The issuer an authenticator app shows, e.g. `vault-example`. */
+  issuer: string;
+  /** Code lifetime. Default `30s`. */
+  period?: string;
+  /** Secret size in bytes. Default 20. */
+  keySize?: number;
+  /** QR code size in pixels; `0` for none. Default 200. */
+  qrSize?: number;
+  /** Default `SHA1` — the one every authenticator app supports. */
+  algorithm?: BaoTotpAlgorithm;
+  /** Default 6. */
+  digits?: 6 | 8;
+  /** Periods of clock skew accepted. Default 1. */
+  skew?: 0 | 1;
+  /** Failed codes before the entity is locked out of this method. Default 5. */
+  maxValidationAttempts?: number;
+}
+
+export interface BaoMfaTotpCanonical {
+  algorithm: string;
+  digits: number;
+  issuer: string;
+  keySize: number;
+  maxValidationAttempts: number;
+  periodSeconds: number;
+  qrSize: number;
+  skew: number;
+}
+
+export interface BaoMfaTotpMethodAttributes extends BaoMfaTotpCanonical {
+  /** The server-made UUID — what a Bao.MfaLoginEnforcement names in `mfaMethodIds`. */
+  methodId: string;
+  name: string;
+  /** `''` for root, `team-a/` below it. */
+  namespacePath: string;
+  digest: string;
+}
+
+const canonical = (input: BaoMfaTotpCanonical): BaoMfaTotpCanonical => ({
+  algorithm: input.algorithm,
+  digits: input.digits,
+  issuer: input.issuer,
+  keySize: input.keySize,
+  maxValidationAttempts: input.maxValidationAttempts,
+  periodSeconds: input.periodSeconds,
+  qrSize: input.qrSize,
+  skew: input.skew,
+});
+
+export const canonicalFromProps = (props: BaoMfaTotpMethodProps): BaoMfaTotpCanonical =>
+  canonical({
+    algorithm: props.algorithm ?? 'SHA1',
+    digits: props.digits ?? 6,
+    issuer: props.issuer,
+    keySize: props.keySize ?? 20,
+    maxValidationAttempts: props.maxValidationAttempts ?? 5,
+    periodSeconds: parseDuration(props.period ?? '30s') ?? -1,
+    qrSize: props.qrSize ?? 200,
+    skew: props.skew ?? 1,
+  });
+
+const num = (value: unknown) => (typeof value === 'number' && Number.isFinite(value) ? value : -1);
+const text = (value: unknown) => (typeof value === 'string' ? value : '');
+
+export const canonicalFromLive = (live: Record<string, unknown>): BaoMfaTotpCanonical =>
+  canonical({
+    algorithm: text(live['algorithm']),
+    digits: num(live['digits']),
+    issuer: text(live['issuer']),
+    keySize: num(live['key_size']),
+    maxValidationAttempts: num(live['max_validation_attempts']),
+    periodSeconds: ttlSeconds(live['period']) ?? -1,
+    qrSize: num(live['qr_size']),
+    skew: num(live['skew']),
+  });
+
+export const attributesOf = (
+  methodId: string,
+  live: Record<string, unknown>,
+): BaoMfaTotpMethodAttributes => {
+  const form = canonicalFromLive(live);
+  return {
+    ...form,
+    digest: sha256(JSON.stringify(form)),
+    methodId,
+    name: text(live['name']),
+    namespacePath: text(live['namespace_path']),
+  };
+};
+
+export const matches = (attributes: BaoMfaTotpMethodAttributes, props: BaoMfaTotpMethodProps) =>
+  attributes.digest === sha256(JSON.stringify(canonicalFromProps(props)));
+
+/** The upsert body — by `method_name`, never `method_id` (mfa-wire.ts). */
+export const writeBody = (props: BaoMfaTotpMethodProps): Record<string, unknown> => {
+  const form = canonicalFromProps(props);
+  return {
+    algorithm: form.algorithm,
+    digits: form.digits,
+    issuer: form.issuer,
+    key_size: form.keySize,
+    max_validation_attempts: form.maxValidationAttempts,
+    method_name: props.name,
+    period: props.period ?? '30s',
+    qr_size: form.qrSize,
+    skew: form.skew,
+  };
+};
+
+/**
+ * The diff's refusal for a changed name, or undefined when the name is unchanged. Never a
+ * `replace`: the ⛔ on a rename in mfa-totp.ts says why.
+ */
+export const renameProblem = (from: string, to: string): string | undefined =>
+  from === to
+    ? undefined
+    : `renaming from \`${from}\` would strand every enrolled secret. Declare the new method as a ` +
+      'second resource, list both ids on the enforcement, enrol, then remove the old one ' +
+      '(mfa-totp.ts).';
+
+export const problems = (props: BaoMfaTotpMethodProps): readonly string[] => {
+  const found: string[] = [];
+  const form = canonicalFromProps(props);
+  if (props.name.trim() === '') found.push('name is empty; it is the only key a declaration has');
+  if (props.issuer.trim() === '') found.push('issuer is empty; the server requires one');
+  if (form.periodSeconds <= 0)
+    found.push(`period \`${props.period ?? ''}\` must be a duration above zero`);
+  if (form.keySize <= 0) found.push('keySize must be above zero');
+  if (form.maxValidationAttempts < 1)
+    found.push('maxValidationAttempts must be at least 1 (0 reads back as 5)');
+  return found;
+};

package/src/openbao/mfa-totp.ts

@@ -0,0 +1,118 @@
+/**
+ * A TOTP login-MFA method — `identity/mfa/method/totp`, found by `method_name`. The method is
+ * policy only: issuer, period, digits. Its `methodId` is what a Bao.MfaLoginEnforcement names.
+ *
+ * ⛔ A RENAME IS REFUSED, NOT REPLACED. A new name is a new method with a new id, and every entity's
+ *   enrolled secret belongs to the OLD id (login_mfa.go validateTOTP reads `entity.MFASecrets[id]`).
+ *   The enforcement would follow the new id in the same deploy, and every enrolled admin would then
+ *   fail MFA — with nobody left able to log in and re-enrol them. The safe move is additive: declare
+ *   the new method as a SECOND resource, list both ids on the enforcement (any one method passes,
+ *   login_mfa.go:831-858), enrol everyone, then drop the old one.
+ * ⛔ DELETING THE METHOD DESTROYS EVERY ENROLLED SECRET FOR IT (mfa-wire.ts deleteTotp) — and with
+ *   openbao/openbao#4030, a deleted enforcement can come back after a restart still naming this id,
+ *   failing every login it matches. `retain` is the default for exactly that reason.
+ *
+ * ★ REPLACE SEMANTICS (REPLACE.md): never `replace`. `name` changed → the plan FAILS (above); any
+ *   other field is an in-place `update`, because the upsert keeps the id.
+ */
+import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import type { BaoError } from './bao-status.ts';
+import {
+  type BaoMfaTotpMethodAttributes,
+  type BaoMfaTotpMethodProps,
+  attributesOf,
+  matches,
+  problems,
+  renameProblem,
+  writeBody,
+} from './mfa-totp-form.ts';
+import { deleteTotp, findTotp, writeTotp } from './mfa-wire.ts';
+
+export type {
+  BaoMfaTotpMethodAttributes,
+  BaoMfaTotpMethodProps,
+  BaoTotpAlgorithm,
+} from './mfa-totp-form.ts';
+
+export interface BaoMfaTotpMethod extends Resource<
+  'Bao.MfaTotpMethod',
+  BaoMfaTotpMethodProps,
+  BaoMfaTotpMethodAttributes,
+  never,
+  HttpClient.HttpClient
+> {}
+
+export const BaoMfaTotpMethod = Resource<BaoMfaTotpMethod>('Bao.MfaTotpMethod', {
+  defaultRemovalPolicy: 'retain',
+});
+
+const refuse = (props: BaoMfaTotpMethodProps, message: string): Effect.Effect<never> =>
+  Effect.die(new Error(`Bao.MfaTotpMethod ${props.name}: ${message}`));
+
+export const readTotp = (
+  props: BaoMfaTotpMethodProps,
+): Effect.Effect<BaoMfaTotpMethodAttributes | undefined, BaoError, HttpClient.HttpClient> =>
+  Effect.map(findTotp(props.name), (found) =>
+    found === undefined ? undefined : attributesOf(found.id, found.live),
+  );
+
+export const planTotp = (
+  props: BaoMfaTotpMethodProps,
+): Effect.Effect<'noop' | 'update', BaoError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    if (problems(props).length > 0) return 'update';
+    const live = yield* readTotp(props);
+    return live !== undefined && matches(live, props) ? 'noop' : 'update';
+  });
+
+/** Upsert by name when live differs, then prove it by reading back. */
+export const reconcileTotp = (
+  props: BaoMfaTotpMethodProps,
+): Effect.Effect<BaoMfaTotpMethodAttributes, BaoError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const bad = problems(props);
+    if (bad.length > 0) return yield* refuse(props, bad.join('; '));
+    const live = yield* readTotp(props);
+    if (live === undefined || !matches(live, props)) yield* writeTotp(writeBody(props));
+    const after = yield* readTotp(props);
+    if (after === undefined)
+      return yield* refuse(props, 'the write succeeded but no method has that name.');
+    if (!matches(after, props)) return yield* refuse(props, 'the method read back different.');
+    return after;
+  });
+
+export const BaoMfaTotpMethodProvider = () =>
+  Provider.effect(
+    BaoMfaTotpMethod,
+    Effect.succeed(
+      BaoMfaTotpMethod.Provider.of({
+        /** ⛔ The namespace's method listing is not a list of things this owns. */
+        list: () => Effect.succeed([]),
+
+        read: Effect.fn(function* ({ olds }) {
+          return yield* readTotp(olds);
+        }),
+
+        diff: Effect.fn(function* ({ news, output }) {
+          if (output === undefined || !isResolved(news)) return undefined;
+          const rename = renameProblem(output.name, news.name);
+          if (rename !== undefined) return yield* refuse(news, rename);
+          return { action: yield* planTotp(news) } as const;
+        }),
+
+        reconcile: Effect.fn(function* ({ news }) {
+          return yield* reconcileTotp(news);
+        }),
+
+        /** ⛔ Read the header first. Idempotent: an unknown id deletes as success. */
+        delete: Effect.fn(function* ({ output }) {
+          yield* deleteTotp(output.methodId);
+          return undefined;
+        }),
+      }),
+    ),
+  );

package/src/openbao/mfa-wire.ts

@@ -0,0 +1,117 @@
+/**
+ * The OpenBao calls behind login MFA: TOTP methods under identity/mfa/method/totp, login
+ * enforcements under identity/mfa/login-enforcement/<name>, and the auth table that turns a mount
+ * path into the accessor an enforcement names.
+ *
+ * ★ OpenBao 2.6.2 SHIPS LOGIN MFA — confirmed in source before any of this was written:
+ *   vault/identity/store.go:312-800 (mfaPaths) registers `mfa/method/totp`, `mfa/login-enforcement/
+ *   <name>` and their listings on the identity backend; vault/identity/mfa.go holds the handlers
+ *   and vault/login_mfa.go the storage.
+ * ★ A TOTP METHOD IS FOUND BY NAME, NOT ID. The id is a server-made UUID; `method_name` is the only
+ *   thing a declaration can know. An update without `method_id` UPSERTS by name within the request's
+ *   namespace (identity/mfa.go:159-230, MemDBMFAConfigByName keys on namespace + name), so the same
+ *   write both creates and updates. The listing (`key_info`, one entry per id, :63-69) answers the
+ *   methods of this namespace AND its parents (login_mfa.go:652-713), so the match also requires
+ *   this namespace's `namespace_path`.
+ * ⛔ THE NAME INDEX IGNORES THE TYPE, SO THIS LISTS EVERY TYPE. login_mfa.go's `name` index is
+ *   (namespace_id, name) across all methods (:1642-1655, :1818), and handleMFAMethodUpdateCommon
+ *   then sets `mConfig.Type = "totp"` on whatever it found (identity/mfa.go:228). A TOTP write under
+ *   the name of a Duo or Okta method would silently CONVERT that method — and every enforcement
+ *   naming its id would start demanding a TOTP code nobody is enrolled for. The per-type listing
+ *   (`.../method/totp?list=true`) cannot see the clash, so this reads the global one
+ *   (`identity/mfa/method?list=true`, store.go:335) and refuses a same-named method of
+ *   another type. ⚠️ The deploying token needs `list` on `identity/mfa/method`.
+ * ⚠️ AN UPDATE BY A STALE `method_id` IS A SILENT NO-OP: the handler returns nil for an unknown id
+ *   (identity/mfa.go:172-183), which HTTP answers 204. So this never writes by id.
+ */
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { BaoEnv, baoCall, baoDelete, baoRead } from './bao-http.ts';
+import { envNamespace, namespacePath } from './bao-namespace.ts';
+import type { BaoError } from './bao-status.ts';
+import { mountPath } from './mount-form.ts';
+
+export const TOTP_PATH = 'identity/mfa/method/totp';
+/** Every MFA method of every type — the only listing that can see a name clash across types. */
+export const METHODS_PATH = 'identity/mfa/method';
+export const enforcementPath = (name: string): string => `identity/mfa/login-enforcement/${name}`;
+
+const record = (value: unknown): Record<string, unknown> | undefined =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+
+/** This call's namespace as OpenBao writes `namespace_path`: `''` or `team-a/`. */
+export const ownNamespacePath: Effect.Effect<string> = Effect.gen(function* () {
+  const env = yield* BaoEnv;
+  return namespacePath(envNamespace(env));
+});
+
+export type TotpEntry = { readonly id: string; readonly live: Record<string, unknown> };
+
+/**
+ * The TOTP method named `name` in this namespace, or undefined. Dies when the name belongs to a
+ * method of ANOTHER type here — writing would convert it (the ⛔ above).
+ */
+export const findTotp = (
+  name: string,
+): Effect.Effect<TotpEntry | undefined, BaoError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const listing = yield* baoRead(`${METHODS_PATH}?list=true`);
+    const info = record(listing?.['key_info']) ?? {};
+    const own = yield* ownNamespacePath;
+    for (const [id, raw] of Object.entries(info)) {
+      const live = record(raw);
+      if (live === undefined || live['name'] !== name || live['namespace_path'] !== own) continue;
+      if (live['type'] !== 'totp') {
+        return yield* Effect.die(
+          new Error(
+            `Bao.MfaTotpMethod ${name}: that name belongs to a ${String(live['type'])} method ` +
+              `(${id}) in this namespace, and a TOTP write would convert it. Pick another name.`,
+          ),
+        );
+      }
+      return { id, live };
+    }
+    return undefined;
+  });
+
+/** Create-or-update by `method_name` — never by id (the ⚠️ above). */
+export const writeTotp = (body: Readonly<Record<string, unknown>>) =>
+  Effect.asVoid(baoCall('write', 'POST', TOTP_PATH, body));
+
+/**
+ * ⛔ DESTROYS EVERY ENTITY'S ENROLLED SECRET FOR THIS METHOD (login_mfa.go:1965-1973 clears the TOTP
+ *   keys under the method id). OpenBao refuses it while an enforcement in memory still names the id
+ *   (:1914-1924) — a refusal this passes on.
+ */
+export const deleteTotp = (id: string) => baoDelete(`${TOTP_PATH}/${id}`);
+
+export const readEnforcement = (name: string) => baoRead(enforcementPath(name));
+
+export const writeEnforcement = (name: string, body: Readonly<Record<string, unknown>>) =>
+  Effect.asVoid(baoCall('write', 'POST', enforcementPath(name), body));
+
+/**
+ * Accessors for auth mount paths, from `GET sys/auth` (keys are `<path>/`). A path with no mount
+ * comes back in `missing`, never as a guess.
+ */
+export const authAccessors = (
+  paths: readonly string[],
+): Effect.Effect<
+  { readonly accessors: readonly string[]; readonly missing: readonly string[] },
+  BaoError,
+  HttpClient.HttpClient
+> =>
+  Effect.gen(function* () {
+    if (paths.length === 0) return { accessors: [], missing: [] };
+    const table = (yield* baoRead('sys/auth')) ?? {};
+    const accessors: string[] = [];
+    const missing: string[] = [];
+    for (const path of paths) {
+      const accessor = record(table[`${mountPath(path)}/`])?.['accessor'];
+      if (typeof accessor === 'string' && accessor !== '') accessors.push(accessor);
+      else missing.push(mountPath(path));
+    }
+    return { accessors, missing };
+  });