From d8c781dffb32028776acb4935f1709ef18ecd1db Mon Sep 17 00:00:00 2001 From: reachableceo Date: Fri, 28 Aug 2026 21:11:10 -0500 Subject: [PATCH] docs: upgrade README to the docs standard MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Purpose kept; adds dated status line, scope/non-goals (no admin UI, memory-only), today-vs-planned table (KNELSecretsManager interim), and links to the porting-notes study plus its open questions for Charles. 💘 Generated with Crush Assisted-by: Crush:glm-5.2 --- README.md | 46 ++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 40 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 792d0d3..7467c7b 100644 --- a/README.md +++ b/README.md @@ -4,16 +4,50 @@ A 100% Go CLI for Bitwarden / Bitwarden Secrets Manager, replacing the Node `bw` CLI in supply-chain-sensitive (CMMC L3/TS posture) environments. One static binary, one auditable vendored module tree, no Node runtime. +Status: 2026-08-28 — spec seed; reference study complete, open questions +pending Charles, no code yet. + +## Scope + - Talks to the Bitwarden Secrets Manager REST API directly with stdlib — NO official SDK (its source-available license is AGPL-incompatible). - Machine-account auth (access-token flow) for headless/agent use; human auth flows where needed. - Porcelain/plumbing model: `bwg get|set|list|sync ...` with JSON out for scripting, plain text for humans. -- Pairs with ukrrs/mopac-keyproxy (placeholder keys to consumers; this CLI - is how material gets INTO the vault) but fully standalone. -- AGPLv3. Part of the MOPAC family; composable by anyone, no org-specific - assumptions in code. +- Memory-only secrets handling: session token held in memory for the + process lifetime and zeroed on exit; values never written to logs, disk + cache, REPORT files, or crash dumps; refs logged only in redacted form. +- Pairs with [ukrrs/mopac-keyproxy](https://git.knownelement.com/ukrrs/mopac-keyproxy) + (placeholder keys to consumers; this CLI is how material gets INTO the + vault) but fully standalone. -Status: specification phase. Building 2026-08-28 onward; reference study -of KNEL/KNELSecretsManager in flight tonight. +## Non-goals + +- No admin UI; a CLI and nothing else. +- Not a vault server — Vaultwarden/Bitwarden stays the store of record. +- No disk cache of secret values; no long-lived persisted sessions by + default (open question 4 below may change that, founder's call). +- Not org-specific: hosts/credentials come from config and environment, + never baked in. + +## Today vs planned + +| | State | +|---|---| +| Today | Spec only (this README + LICENSE). Interim in production: the KNELSecretsManager containerized `bw` wrapper (ADR-002) — plain `bw` behind docker, plaintext env on disk, full login/unlock/sync per call. | +| Planned | Go CLI per the reference study: `bw:` key-ref resolution for the MOPAC harness, lookup by item name (password field), per-process unlock, never `bw logout`, typed not-found/unlock errors, fake-bw test stub. | + +## Design references + +- [KNELSecretsManager study — current surface, replacement design sketch, open questions](https://git.knownelement.com/ukrrs/MOPAC/src/branch/main/docs/PORTING-NOTES-secrets.md) + (section 3 lists seven open questions for Charles: substrate, machine + account, ref syntax, session lifetime, secret names, scope, subprocess + injection) +- [MOPAC harness DESIGN.md — Toolchain policy, 100% Go HARD RULE](https://git.knownelement.com/ukrrs/MOPAC/src/branch/main/DESIGN.md#user-content-toolchain-policy-charles-2026-08-28-evening--hard-rule) +- [MOPAC harness DESIGN.md — Key proxy](https://git.knownelement.com/ukrrs/MOPAC/src/branch/main/DESIGN.md#user-content-key-proxy-placeholders-only-material-never-leaves-the-vault-charles-2026-08-28-evening) +- Parent: [ukrrs/MOPAC](https://git.knownelement.com/ukrrs/MOPAC) — the harness whose `bw:` key refs this unblocks + +## License + +AGPLv3 — see [LICENSE](LICENSE).