From 325a36cc35a37cb9f1c2db26b5595111fdf41784 Mon Sep 17 00:00:00 2001 From: reachableceo Date: Fri, 28 Aug 2026 21:11:09 -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, and navigable links into the ukrrs/MOPAC design docs. 💘 Generated with Crush Assisted-by: Crush:glm-5.2 --- README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 45 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index bd79014..b0b6645 100644 --- a/README.md +++ b/README.md @@ -5,14 +5,49 @@ opaque placeholder keys; real secrets live only in Bitwarden Secrets Manager and/or HashiCorp Vault and are resolved to real material at the wire, in memory, never persisted, with no admin UI to attack. -- Placeholders in, real keys on the wire out (`mpk_...` refs; a leaked - placeholder is revoke-and-remap, not an incident). -- Backends: Bitwarden Secrets Manager REST (machine accounts) and HashiCorp - Vault KV v2 + AppRole. Stdlib-first; no Bitwarden SDK (license). -- Serves as both an HTTP hop and a CLI (`keyproxy get ` for exec-style - plumbing). -- AGPLv3. Part of the MOPAC family but standalone and composable: generic, - config-driven, no organizational assumptions baked into code. +Status: 2026-08-28 — spec seed; design frozen, no code yet. -Status: specification phase (see MOPAC/harness/DESIGN.md, "Key proxy"). -Building 2026-08-28 onward. +## Scope + +- Placeholders in, real keys on the wire out: consumers (harness, CLIs, + containers) hold `mpk_...` opaque refs only. A leaked placeholder is + revoke-and-remap, not an incident — zero upstream exposure. +- Backends: Bitwarden Secrets Manager REST (machine accounts) and HashiCorp + Vault KV v2 + AppRole (official Go api pkg is MPL-2.0, vendored). + Stdlib-first; NO official Bitwarden SDK (its source-available license is + AGPL-incompatible). +- Two shapes, one resolver: an HTTP hop for services, and a CLI + (`keyproxy get `) for exec-style plumbing. +- Memory-only material handling: fetch-on-demand, short TTL, never persisted, + never written to logs; ref redaction everywhere. +- Config-driven: generic, no organizational hosts/paths/defaults baked into + code. + +## Non-goals + +- No admin UI — there is no admin surface at all; configuration only. +- Not a secrets manager: the vault stays authoritative; keyproxy never + becomes a second place secrets live. +- No persistence of key material to disk, cache files, or crash dumps. +- Not org-specific: TSYS policy lives outside this repo (loose-coupling + rules for the MOPAC tool family). + +## Today vs planned + +| | State | +|---|---| +| Today | Spec only (this README + LICENSE). Design carried in the MOPAC harness DESIGN.md "Key proxy" section. | +| Planned | Go implementation: placeholder->material resolver, Bitwarden Secrets Manager + Vault connectors, HTTP hop + `get` CLI, ref-redaction rules. | + +## Design references + +- [MOPAC harness DESIGN.md — Key proxy: placeholders only, material never leaves the vault](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) +- [MOPAC harness DESIGN.md — Tooling = standalone public FLOSS repos](https://git.knownelement.com/ukrrs/MOPAC/src/branch/main/DESIGN.md#user-content-tooling--standalone-public-floss-repos-loosely-coupled-charles-2026-08-28-evening) +- [Exposure-minimization protocol (crush porting notes)](https://git.knownelement.com/ukrrs/MOPAC/src/branch/main/docs/PORTING-NOTES-crush.md) +- Sibling: [mopac-bitwarden-go](https://git.knownelement.com/ukrrs/mopac-bitwarden-go) — how material gets INTO the vault +- Parent: [ukrrs/MOPAC](https://git.knownelement.com/ukrrs/MOPAC) — the harness this serves + +## License + +AGPLv3 — see [LICENSE](LICENSE). (MIT fallback only if a license conflict +still arises; none known today.)