173 lines
8.3 KiB
Markdown
173 lines
8.3 KiB
Markdown
# REPORT — mopac-bitwarden-go v0: Bitwarden Secrets Manager REST client (fake-server tested)
|
|
|
|
- Date: 2026-08-28 23:30 (work session 2026-08-28 late)
|
|
- Repo: https://git.knownelement.com/ukrrs/mopac-bitwarden-go (main, pushed:
|
|
`643de0f..9b730af`, 6 commits after the spec seed)
|
|
- Local: ~/projects/meta/MOPAC/bitwarden-go
|
|
- Status: v0 COMPLETE and green. Stdlib-only Go (zero third-party
|
|
modules), ALL dev in Docker (digest-pinned golang:1.26-bookworm, same
|
|
image as keyproxy), built and tested entirely against a fake Secrets
|
|
Manager — no live vault access exists on this account yet; live creds
|
|
attach later with zero code change (config only).
|
|
|
|
## 1. What was built
|
|
|
|
A plain-REST Bitwarden Secrets Manager client for machine accounts +
|
|
thin CLI. No official SDK imported (AGPL-incompatible); the wire protocol
|
|
was reconstructed from Bitwarden's public API behavior and pinned to
|
|
published SDK test vectors.
|
|
|
|
Wire protocol implemented (all verified against the fake server):
|
|
|
|
| Step | Wire |
|
|
|---|---|
|
|
| login | POST /identity/connect/token — grant_type=client_credentials, scope=api.secrets, machine client_id/client_secret |
|
|
| org key | response's `encrypted_payload`: type-2 EncString sealed for the credential's embedded 16-byte key (HKDF-SHA256, salt `bitwarden-accesstoken`, info `sm-access-token`); unwraps to the organization key |
|
|
| refresh | grant_type=refresh_token, fired automatically 30s before expiry (memory-only) |
|
|
| secrets | GET /api/accounts/{id}/secrets, GET /api/secrets/{id}, GET /api/projects/{id}/secrets; names/values are EncStrings decrypted in memory with the org key |
|
|
| projects | GET /api/accounts/{id}/projects |
|
|
|
|
Machine credential format handled: `0.<uuid>.<secret>:<b64-16B-key>` as
|
|
printed by Secrets Manager (uuid -> client_id; secret -> client_secret;
|
|
key -> payload-unwrap derivation). Split BW_CLIENTID/BW_CLIENTSECRET also
|
|
accepted (plaintext-mode servers only).
|
|
|
|
## 2. Library surface (the exact keyproxy integration contract)
|
|
|
|
```go
|
|
import bw "git.knownelement.com/ukrrs/mopac-bitwarden-go"
|
|
|
|
tok, err := bw.Authenticate(ctx, bw.Credentials{BaseURL: url, AccessToken: cred})
|
|
defer tok.Zero()
|
|
value, err := bw.GetSecret(ctx, tok, "redmine-api-key") // secret NAME or uuid
|
|
secrets, err := bw.ListSecrets(ctx, tok) // metadata only, no values
|
|
projects, err := bw.ListProjects(ctx, tok)
|
|
```
|
|
|
|
- Errors are `errors.Is`-friendly sentinels: ErrAuthFailed,
|
|
ErrTokenExpired, ErrSecretNotFound, ErrMalformedResponse, ErrDecrypt,
|
|
ErrServer, ErrUnreachable, ErrInvalidCredentials. Error strings carry
|
|
fixed reason enums + uuids/names ONLY — never values, tokens,
|
|
ciphertext, or response bodies.
|
|
- Token: memory-only, auto-refresh-before-expiry, `Zero()` wipes key
|
|
material, `String()` is log-safe (expiry + ids only).
|
|
- Decryption fails closed: MAC verified before decrypt; tampering is a
|
|
typed error, never passthrough of ciphertext.
|
|
|
|
## 3. CLI usage
|
|
|
|
```
|
|
bitwarden-go login # credential check; prints summary only
|
|
bitwarden-go projects # "<id> <name>" per line
|
|
bitwarden-go secrets list # "<id> <name>" per line
|
|
bitwarden-go get <name-or-uuid> # bare value to stdout, no newline
|
|
```
|
|
|
|
Config: BW_* env vars or 0600 env file ($BITWARDENGO_CONFIG, default
|
|
~/.config/bitwarden-go/env). NEVER flags/args. Keys: BW_SERVER_URL
|
|
(default https://vault.bitwarden.com), BW_ACCESS_TOKEN (full credential)
|
|
or BW_CLIENTID+BW_CLIENTSECRET. Exit codes 0/1/2 mirror keyproxy
|
|
(ok / usage-config / auth-or-resolution).
|
|
|
|
## 4. Fake-server test results
|
|
|
|
`./dev.sh check` (in the Docker builder): build + vet + gofmt clean,
|
|
**53 tests pass, 0 fail** across 3 packages (38 top-level + 15 subtests).
|
|
Coverage areas:
|
|
|
|
- Crypto pinned to published SDK vectors: credential parsing, HKDF
|
|
shareable-key derivation (3 vectors), type-2 EncString AE vector,
|
|
round-trips, tamper detection (MAC + ciphertext).
|
|
- Auth table vs fake server: happy path, wrong secret, server 500,
|
|
unreachable, malformed token body, split-creds-on-encrypted-server
|
|
(fails loudly), plaintext server mode.
|
|
- Token lifecycle: refresh-before-expiry (short-TTL), refresh rejection
|
|
surfacing, expiry without refresh token, omitted-value list fallback to
|
|
by-id fetch.
|
|
- Reads: by name, by uuid, lists with decrypted names, missing secret
|
|
(name + uuid), malformed list body, tampered value MAC, rejected
|
|
bearer.
|
|
- Config: 0600 enforcement (0644/0666 refused BEFORE read; 0400 passes),
|
|
env-over-file precedence, pure-Go KEY=VALUE discipline, missing-file
|
|
behavior, no-credentials error.
|
|
- CLI (end-to-end via real 0600 env file): login/get/lists/failure
|
|
paths/usage.
|
|
- Redaction sweeps: every error path and every CLI run asserted free of
|
|
client secret, credential key, access/refresh tokens, secret values;
|
|
stdout carries material only in `get` (pinned to the exact value).
|
|
|
|
Smoke (`./dev.sh smoke`): fake Secrets Manager booted in a container on
|
|
127.0.0.1:8600 (full crypto chain, random org key per boot); real binary
|
|
driven from host: login/projects/secrets list/get by name/get by
|
|
uuid/missing-secret/bad-credential + redaction sweep. Result: `smoke: OK`.
|
|
Exact container IDs cleaned up; no broad kills.
|
|
|
|
## 5. Open questions from PORTING-NOTES-secrets.md §3
|
|
|
|
Answered by code (v0 decision, reversible):
|
|
|
|
1. Substrate: direct REST in Go, zero Node/bw. The client implements the
|
|
machine-account flow including client-side decryption, so shelling to
|
|
`bw` is unnecessary for the harness's read needs.
|
|
3. Ref syntax (read side): `bw:<name>` maps to GetSecret(name) = Secrets
|
|
Manager secret by NAME (uuid also accepted). `#field`/`#totp` are
|
|
vault-item concepts; Secrets Manager secrets have no fields — code
|
|
answer: not needed for the SM path.
|
|
4. Session lifetime: memory-only for the process lifetime; a long-lived
|
|
keyproxy keeps its Token and auto-refreshes before expiry (30s skew).
|
|
No disk persistence exists in the library at all.
|
|
|
|
Still needing Charles:
|
|
|
|
2. Machine account: dedicated service account for keyproxy/harness (not
|
|
coo@turnsys.com), with access scoped to a harness project; the vault
|
|
side must exist before phase 3 flips on.
|
|
5. Secret inventory: exact secret names/uuids for Redmine + LiteLLM keys
|
|
(current fake names redmine-api-key/litellm-key are placeholders).
|
|
6. Scope: strictly the SM read path consumed via keyproxy, or also absorb
|
|
KNELCredsManager's ~/.creds/*.env contract.
|
|
7. Subprocess injection: does anything need secrets as child-process env
|
|
(LiteLLM), or HTTP-header-only as today?
|
|
+ NEW — module wiring: keyproxy must consume this module from the private
|
|
gitea; recommend `go mod vendor` (matches "one auditable vendored
|
|
module tree") or GOPRIVATE=git.knownelement.com. Founder's call.
|
|
+ NEW — live verification checklist (first day with real creds): run
|
|
login/get against Vaultwarden pwvault.turnsys.com and against Bitwarden
|
|
cloud to confirm the accounts-path list endpoint and encrypted_payload
|
|
shapes match the fake exactly (protocol reconstructed from public
|
|
behavior + SDK vectors; end-to-end vs a live server is the one thing
|
|
tests cannot prove).
|
|
|
|
## 6. Exact keyproxy integration point
|
|
|
|
`keyproxy/internal/backend/bitwarden.go` (currently the 501 stub,
|
|
`Resolve` at bitwarden.go:20). Phase 3 replacement sketch:
|
|
|
|
```go
|
|
// keyproxy: internal/backend/bitwarden.go
|
|
func (b *Bitwarden) Resolve(ctx context.Context, ref Ref) (string, error) {
|
|
cfg, err := config.Load(ref.Source) // ref.Source = 0600 env file path (BW_* keys)
|
|
if err != nil { return "", Err(ref, b.Name(), ReasonUnreadableSource) }
|
|
tok, err := bw.Authenticate(ctx, bw.Credentials{
|
|
BaseURL: cfg.ServerURL, AccessToken: cfg.AccessToken,
|
|
ClientID: cfg.ClientID, ClientSecret: cfg.ClientSecret,
|
|
})
|
|
if err != nil { return "", Err(ref, b.Name(), ReasonUnreadableSource) } // auth -> typed reason
|
|
defer tok.Zero()
|
|
return bw.GetSecret(ctx, tok, ref.Key) // ref.Key = secret name or uuid
|
|
}
|
|
```
|
|
|
|
keyproxy.toml ref shape (existing stub semantics): backend `bitwarden`,
|
|
source = path to the 0600 env file, key = secret name/uuid. The library's
|
|
typed errors map 1:1 onto keyproxy's Reason enums. Wiring requires adding
|
|
the module dependency (see open question: vendor vs GOPRIVATE).
|
|
|
|
## 7. Reproduce
|
|
|
|
```
|
|
cd ~/projects/meta/MOPAC/bitwarden-go
|
|
./dev.sh check # build + vet + test (Docker builder)
|
|
./dev.sh smoke # containerized fake server + real CLI end-to-end
|
|
```
|