# Porting notes: KNELSecretsManager (reference/KNELSecretsManager)

Scope for MOPAC harness: Bitwarden secret retrieval for `bw:` key refs
(reserved in `internal/config/keys.go:34-35`, errors until "phase 3").
DESIGN.md: Go `bitwarden-go` wrapper replaces KNELSecretsManager; secrets
never in logs. Line refs from study 2026-08-28, drift possible.

Status: 2026-08-28 — complete; open questions for Charles pending (section 3), feeds ukrrs/mopac-bitwarden-go.

## 1. Current surface

Two generations ship in the repo; ADR-002 (`docs/ADR-002-ContainerBW.md`)
supersedes the standalone script with a containerized `bw` wrapper.

**Legacy `secrets-manager.sh` (v2.0)** — single bash script, CLI only:
`install | get <name> | list | test`, `-c/--config FILE`. Every invocation
redoes the full lifecycle: source plaintext config (BW_SERVER_URL,
BW_CLIENTID, BW_CLIENTSECRET, BW_PASSWORD) -> `bw config server` ->
`bw logout` -> `bw login --apikey` -> `bw unlock --raw` -> `bw get password
<name>` (secrets-manager.sh:119-159). Exit codes 10/20/30/40/50/60/70
(config/bw-missing/install/server/session/secret/login). Logs to
`/tmp/secrets-manager.sh.log` (names, not values). Designed to be vendored
into shell frameworks; Makefile lint/test/vendor-test targets.

**Current container wrapper (production since 2026-08-13, ADR-002)**:
- `bin/bw-install.sh` — downloads pre-compiled bw `2026.7.0` (inside an
  alpine container; no host Node/wget), builds `reachableceo-bw-native:
  2026.7.0` (debian:bookworm-slim + ca-certificates, `docker/bw-native/
  Dockerfile`), installs wrapper to `~/.local/bin/bw` + entrypoint to
  `~/.local/share/bw/entrypoint.sh`.
- `bin/bw-cli.sh` (host) — loads `~/.config/bw/env` (single-quoted values,
  mode 600; the only secrets-on-disk allowed org-wide), then `docker run`
  with named volume `tsys-bw-cli-state` mounted at `/root/.config/Bitwarden
  CLI` so login state persists across calls.
- `bin/bw-entrypoint.sh` (container) — idempotent: `bw config server` ->
  `bw login --apikey` (no TOTP; API key minted from an authenticated web
  session) -> `bw unlock --passwordfile` (password briefly in /tmp) ->
  `bw sync` -> `exec bw "$@"` with BW_SESSION.
- Interface is transparent `bw`: `status | list items/collections | get
  password|totp|item <name> | generate`. Lookup is by item **name**; the
  default secret is the item's password field (e.g. `APIKEY-pushover`).
- Backend: Vaultwarden at `https://pwvault.turnsys.com`, machine account
  `coo@turnsys.com`, API-key auth + master-password unlock.

**Consumers**: nothing in the MOPAC harness consumes it yet — sole planned
integration is the `bw:` key-ref prefix (`internal/config/keys.go`,
asserted by `config_test.go:126,130`; `harness.toml.example:5`). First
real secrets needed: Redmine API key + LiteLLM key (`[redmine] key_ref`,
`[litellm] key_ref`). Siblings still on Bitwarden: KNELCredsManager
(`~/.creds/*.env` feeder) and `mcp-bitwarden-wrapper.sh` in
KNEL-AIMiddleware.

**Weaknesses to fix in the port**: plaintext master password + API secret
on disk; full login/unlock/sync per call (slow, racy logout in legacy);
secret values echoed to stdout and captured by callers into env; docker
required per host; "native" bw binary is secretly a Node SEA (ADR-002
caveat); legacy script `bw logout`s any concurrent session.

## 2. Replacement design sketch (Go)

**Shape**: `internal/secrets` package + thin `MOPAC/tools/bitwarden-go`
CLI (per DESIGN.md:88) so both harness and humans share one resolver.
Config gains `ResolveKeyRef` case for `bw:REF` (keys.go already reserves
it; keep `redact()` semantics).

**bw execution**: exec `bw` from PATH (the ADR-002 wrapper makes it
transparent whether bw is native or containerized). Treat as opaque
subprocess: `bw get password <name> --session <tok> --nointeraction`,
JSON mode where useful (`bw get item <name>`), 30s timeout, capture
stdout into a `[]byte` not a logged string.

**Machine credentials** (bootstrapping only): prefer env
`BW_CLIENTID/BW_CLIENTSECRET/BW_PASSWORD`; fallback `~/.config/bw/env`
parsed by hand (single-quoted values, require mode 0600). Never in
harness.toml, never in logs. Server URL from env `BW_SERVER` with
Vaultwarden default.

**Unlock strategy**: once per process — config server (idempotent),
`bw login --apikey` (skip if `bw status` says logged in), `bw unlock
--passwordenv BW_PASSWORD --raw` -> session key held **in memory only**;
single `bw sync` after login. On session-expired error mid-run: re-unlock
once, then fail. Never `bw logout` (breaks concurrent clients).

**Lookup by key**: `bw:<item-name>` -> password field (matches current
usage). Optional `bw:<name>#<field>` and `bw:<name>#totp` if non-password
fields are needed. Not-found => typed `ErrSecretNotFound`; auth failures
=> `ErrUnlockFailed` (mirrors exit codes 60/50/70 for callers).

**Caching**: per-run in-memory `map[ref]string` + mutex (multi-vertical
workers may resolve concurrently); negative results cached too. Session
token cached for process lifetime, zeroed on exit. No disk cache of
values; optional disk persistence of BW_SESSION is an open question.

**Never-log rules** (extends keys.go:70-78): log refs only as
`bw:<name>****`; error strings never embed values; subprocess stderr from
bw is scrubbed/dropped (bw can echo fragments); secrets never written to
REPORT.md, spans, or crash dumps; `go test` uses fake bw stub, never the
real vault.

## 3. Open questions for Charles

1. **Substrate**: keep shelling out to `bw` (containerized per ADR-002,
   Docker on every harness host) or implement the Vaultwarden REST API
   directly in Go (truly zero Node/bw, but reimplements crypto + sync)?
   DESIGN.md:84 says "replaces Node bw CLI dependency" — which side of
   that line do you want?
2. **Machine account**: dedicated service account for the harness instead
   of `coo@turnsys.com`, with a vault collection scoped to only the
   secrets the harness needs?
3. **Ref syntax**: is `bw:<item-name>` (password field) sufficient for
   v1, or do you want `#field` / `#totp` / collection-scoped refs now?
4. **Session lifetime**: unlock per `harness once` run only, or persist
   BW_SESSION (0600, TTL) across runs to avoid unlock cost each start?
5. **Secret inventory + names**: confirm exact vault item names for
   Redmine and LiteLLM keys so `key_ref` values can be pinned in
   harness.toml.example.
6. **Scope of port**: absorb KNELCredsManager's `~/.creds/*.env`
   contract too, or strictly the `bw:` refs used by the harness?
7. **Subprocess injection**: any consumers needing secrets as env vars
   for child processes (LiteLLM?), vs HTTP-header-only as today?