Decision memo — OpenBao positioning: test-only vs. supported bundled backend

• Status: DECISION: Option A (test-only) — applied 2026-07-04 (Sprint 20260703_005 D4). The operator ruled OpenBao is a dev/CI test-only convenience, not a shipped/supported bundled backend. The Option-A file list below has been applied:
  • ADR-031 §D5 amended (test-only reframe; rationale retained);
  • NOTICE.md + docs/legal/THIRD-PARTY-DEPENDENCIES.md reframed to dev/test tooling, not distributed ⇒ MPL-2.0 distribution obligations do not attach;
  • third-party-licenses/OpenBao-MPL-2.0.txt removed (courtesy copy of a component Stella Ops does not redistribute; its provenance was also non-canonical — see the hygiene note under Option B);
  • devops/compose/docker-compose.openbao.yml + docker-compose.secret-providers.override.yml + env/stellaops.env.example retitled TEST-ONLY (profile remains opt-in, never in the default up);
  • runbook secret-provider-multi-provider.md + operator guide secrets-and-keys-guide.md wording updated (Vault flagship external + builtin floor; OpenBao test-only);
  • verified no release manifest pins or ships an OpenBao image.
• Date: 2026-07-03 (memo) / 2026-07-04 (decision applied)
• Owner (decision): Operator / Product. Prepared by: Documentation author (Sprint 20260703_005, D4).
• Relates to: ADR-031 §D5, NOTICE.md, docs/legal/THIRD-PARTY-DEPENDENCIES.md, third-party-licenses/OpenBao-MPL-2.0.txt (removed 2026-07-04), devops/compose/docker-compose.openbao.yml.

The body below is the original decision-support text, kept as the record of the choice as presented. Option A was chosen and applied.

The inconsistency to resolve

Every committed artifact today presents OpenBao (MPL-2.0, Linux Foundation fork of HashiCorp Vault) as an OPTIONAL bundled runtime broker:

But the operator has stated OpenBao is test-only, and the live-proof note in the multi-provider runbook already records that: “In that proof, OpenBao was a TEST-ONLY backend (ephemeral container via the opt-in profile), not a shipped default.” (secret-provider-multi-provider.md).

So “bundled optional broker” (the artifacts) and “test-only” (the operator) are in tension. This needs one authoritative answer because the licensing and supply-chain obligations differ between the two.

Note (unchanged either way): the product default secret backend stays builtin. This decision is only about how OpenBao is positioned, supported, and licensed — not about the default.

Option A — Test-only (dev/CI convenience, not shipped, not supported)

OpenBao is used only for local development and automated tests via the opt-in compose profile. It is not part of any released/supported bundle and is never pinned/shipped in a release. The only supported external secret backend is an operator-run HashiCorp Vault (or an operator-run OpenBao they stand up themselves).

Licensing consequence: Stella Ops does not distribute the OpenBao image as part of the product, so MPL-2.0 distribution obligations do not attach. OpenBao is classified as dev/test tooling (like the dev-only NuGet/npm dependencies), not a distributed runtime component. The third-party-licenses/ text becomes an optional courtesy rather than a distribution requirement.

To apply (if chosen — DO NOT do this yet):

• ADR-031 D5: soften “bundled broker” → “test-only reference backend for dev/CI; not shipped or supported in a release.”
• NOTICE.md + THIRD-PARTY-DEPENDENCIES.md: move OpenBao from runtime/infrastructure to Dev/Test tooling; drop the “bundled runtime image” framing.
• devops/compose/docker-compose.openbao.yml: retitle as a dev/test profile; state explicitly it is never part of a release bundle.
• Ensure no release manifest pins/ships an OpenBao image.

Trade-off: smaller supported surface; operators wanting a turnkey Vault-shaped bundled broker have none — they must run their own Vault/OpenBao.

Option B — Supported bundled backend (the current ADR-031 D5 intent)

OpenBao is a supported, optional secret backend that Stella ships (image pinned by sha256 digest in the release bundle) and supports in production.

Licensing consequence: Stella distributes the OpenBao runtime image as part of the product, so MPL-2.0 obligations do attach — and are already met: NOTICE + THIRD-PARTY entries + license text under third-party-licenses/, runtime image only, no source vendoring. MPL-2.0 is file-level copyleft; Stella’s separate, unmodified runtime use triggers no source-disclosure obligation.

To keep it clean (if chosen — DO NOT do this yet):

• Pin by digest: the release bundle must carry OPENBAO_IMAGE as an immutable openbao/openbao@sha256:<digest> (supply-chain rule; the compose file already flags this). A floating tag in a release is a contract break.
• License-text hygiene: third-party-licenses/OpenBao-MPL-2.0.txt currently records its provenance as “Extracted 2026-06-23 from the local installed Insomnia license bundle” — replace it with the canonical MPL-2.0 text from the OpenBao project so the shipped license text is authentic to the component.
• Ongoing duty: track OpenBao CVEs/updates as a supported component and refresh the pinned digest.

Trade-off: larger supported surface + release/CVE responsibility, in exchange for a turnkey bundled broker.

Recommendation (for the operator to accept or override)

If the operator’s “test-only” statement is definitive, Option A is the cheapest reconciliation and removes the distribution/CVE burden — but it narrows the supported backends to builtin + operator-run Vault. If a turnkey bundled broker is genuinely wanted, Option B is already 90% in place; the only real work is digest-pinning discipline in the release bundle plus the license-text provenance fix.

Either way, the artifacts must stop saying two different things. The builtin default is unaffected. This memo does not change any file — the choice is the operator’s.