feat: MSX_STORE_KEY multi-mode support (unsafe-plain, aes-256-gcm, keyring) (#6)

- Adds keyring mode using github.com/99designs/keyring (macOS Keychain,
  Linux Secret Service, Windows DPAPI). Auto-generates key if none exists.
- Adds unsafe-plain mode: explicit plain text with no warning.
- When MSX_STORE_KEY is unset, defaults to unsafe-plain but prints a
  clear warning to stderr on every invocation.
- aes-256-gcm:<hex> now uses the aes-256-gcm: prefix (breaking change from
  bare hex/base64 key format).
- Consistency enforcement preserved: mode mismatch on read → clear error.
- Updates README with full mode documentation.
- Adds tests for mode parsing, warning behaviour, and round-trip.

Closes #6

Author: corruptmem

README.md

@@ -78,33 +78,72 @@ Default state location:
 Override with:
 - `MSX_HOME=/some/path`
 
-### Optional encryption at rest
+### Token store encryption (`MSX_STORE_KEY`)
 
-By default msx relies on filesystem permissions (`0700` dir, `0600` DB file).
-For environments that require more, set `MSX_STORE_KEY` to a 32-byte key:
+`MSX_STORE_KEY` controls how token values are stored on disk.  Three modes
+are supported:
+
+| Value | Behaviour |
+|---|---|
+| *(not set)* | Plain text, **warning printed to stderr** on every invocation. |
+| `unsafe-plain` | Plain text, warning suppressed (explicit acknowledgement). |
+| `aes-256-gcm:<hex-key>` | AES-256-GCM encryption; key is 32 bytes as 64 hex chars. |
+| `keyring` | Key stored in / retrieved from the platform keyring (see below). |
+
+Token values are encrypted in the bbolt store using **AES-256-GCM** with a
+random 12-byte nonce per write.  Profile metadata (client ID, authority,
+scopes) is not encrypted.
+
+**Consistency is enforced**: if stored tokens were written in one mode and
+read in another, msx will fail with a clear error rather than silently
+mis-reading data.
+
+#### `aes-256-gcm` mode
 
 ```sh
 # Generate a key (store it somewhere safe — 1Password works well):
 openssl rand -hex 32
 
-# Then export it in every shell session that runs msx:
-export MSX_STORE_KEY=<64 hex chars>
+# Export it in every shell session that runs msx:
+export MSX_STORE_KEY=aes-256-gcm:<64-hex-chars>
 ```
 
-When the variable is set, token values are encrypted in the bbolt store using
-**AES-256-GCM** with a random 12-byte nonce per write.  Profile metadata
-(client ID, authority, scopes) is not encrypted.
-
-Key management expectations:
 - The key is **never persisted to disk** by msx.  You are responsible for keeping it.
 - If you lose the key you can still recover tokens using `state-export` while
   the key is available, then reinstate them with `state-import` once you have
   a replacement.
-- Consistency is enforced: if a key is set but stored tokens are plain (or
-  vice versa), msx will fail with a clear error rather than silently
-  mis-reading data.
-- Encryption is optional.  Plain-mode operation (no key) is the default and
-  remains fully supported.
+- Best for: automation, CI/CD, scripts where you control the environment.
+
+#### `keyring` mode
+
+```sh
+export MSX_STORE_KEY=keyring
+```
+
+msx uses the platform keyring to store and retrieve the encryption key:
+- **macOS** — Keychain
+- **Linux** — Secret Service (GNOME Keyring / KWallet) with a file-backend
+  fallback for headless environments
+- **Windows** — DPAPI / Windows Credential Manager
+
+If no key exists yet, msx generates a 32-byte random key and saves it
+automatically.  The key is stored under service `msx`, item `store-key`.
+
+- Best for: interactive developer machines where you want zero key management.
+- Note: may prompt interactively on some platforms.  For automation use
+  `aes-256-gcm:<hex-key>` instead.
+
+#### `unsafe-plain` mode
+
+```sh
+export MSX_STORE_KEY=unsafe-plain
+```
+
+Tokens are stored as plain JSON.  This is the default when `MSX_STORE_KEY` is
+absent, but setting it explicitly suppresses the startup warning.
+
+- Best for: trusted single-user machines or environments where filesystem
+  permissions (`0700` dir, `0600` DB file) are your only security boundary.
 
 Stored per profile:
 - authority / tenant hint

go.mod

@@ -4,4 +4,14 @@ go 1.26
 
 require go.etcd.io/bbolt v1.4.3
 
-require golang.org/x/sys v0.29.0 // indirect
+require (
+	github.com/99designs/go-keychain v0.0.0-20191008050251-8e49817e8af4 // indirect
+	github.com/99designs/keyring v1.2.2
+	github.com/danieljoos/wincred v1.1.2 // indirect
+	github.com/dvsekhvalnov/jose2go v1.5.0 // indirect
+	github.com/godbus/dbus v0.0.0-20190726142602-4481cbc300e2 // indirect
+	github.com/gsterjov/go-libsecret v0.0.0-20161001094733-a6f4afe4910c // indirect
+	github.com/mtibben/percent v0.2.1 // indirect
+	golang.org/x/sys v0.29.0 // indirect
+	golang.org/x/term v0.3.0 // indirect
+)

go.sum

@@ -1,14 +1,40 @@
+github.com/99designs/go-keychain v0.0.0-20191008050251-8e49817e8af4 h1:/vQbFIOMbk2FiG/kXiLl8BRyzTWDw7gX/Hz7Dd5eDMs=
+github.com/99designs/go-keychain v0.0.0-20191008050251-8e49817e8af4/go.mod h1:hN7oaIRCjzsZ2dE+yG5k+rsdt3qcwykqK6HVGcKwsw4=
+github.com/99designs/keyring v1.2.2 h1:pZd3neh/EmUzWONb35LxQfvuY7kiSXAq3HQd97+XBn0=
+github.com/99designs/keyring v1.2.2/go.mod h1:wes/FrByc8j7lFOAGLGSNEg8f/PaI3cgTBqhFkHUrPk=
+github.com/danieljoos/wincred v1.1.2 h1:QLdCxFs1/Yl4zduvBdcHB8goaYk9RARS2SgLLRuAyr0=
+github.com/danieljoos/wincred v1.1.2/go.mod h1:GijpziifJoIBfYh+S7BbkdUTU4LfM+QnGqR5Vl2tAx0=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/dvsekhvalnov/jose2go v1.5.0 h1:3j8ya4Z4kMCwT5nXIKFSV84YS+HdqSSO0VsTQxaLAeM=
+github.com/dvsekhvalnov/jose2go v1.5.0/go.mod h1:QsHjhyTlD/lAVqn/NSbVZmSCGeDehTB/mPZadG+mhXU=
+github.com/godbus/dbus v0.0.0-20190726142602-4481cbc300e2 h1:ZpnhV/YsD2/4cESfV5+Hoeu/iUR3ruzNvZ+yQfO03a0=
+github.com/godbus/dbus v0.0.0-20190726142602-4481cbc300e2/go.mod h1:bBOAhwG1umN6/6ZUMtDFBMQR8jRg9O75tm9K00oMsK4=
+github.com/gsterjov/go-libsecret v0.0.0-20161001094733-a6f4afe4910c h1:6rhixN/i8ZofjG1Y75iExal34USq5p+wiN1tpie8IrU=
+github.com/gsterjov/go-libsecret v0.0.0-20161001094733-a6f4afe4910c/go.mod h1:NMPJylDgVpX0MLRlPy15sqSwOFv/U1GZ2m21JhFfek0=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
+github.com/mtibben/percent v0.2.1 h1:5gssi8Nqo8QU/r2pynCm+hBQHpkB/uNK7BJCFogWdzs=
+github.com/mtibben/percent v0.2.1/go.mod h1:KG9uO+SZkUp+VkRHsCdYQV3XSZrrSpR3O9ibNBTZrns=
+github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e/go.mod h1:zD1mROLANZcx1PVRCS0qkT7pwLkGfwJo4zjcN/Tysno=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
 github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 go.etcd.io/bbolt v1.4.3 h1:dEadXpI6G79deX5prL3QRNP6JB8UxVkqo4UPnHaNXJo=
 go.etcd.io/bbolt v1.4.3/go.mod h1:tKQlpPaYCVFctUIgFKFnAlvbmB3tpy1vkTnDWohtc0E=
 golang.org/x/sync v0.10.0 h1:3NQrjDixjgGwUOCaF8w2+VYHv0Ve/vGYSbdkTa98gmQ=
 golang.org/x/sync v0.10.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
+golang.org/x/sys v0.0.0-20210819135213-f52c844e1c1c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.29.0 h1:TPYlXGxvx1MGTn2GiZDhnjPA9wZzZeGKHHmKhHYvgaU=
 golang.org/x/sys v0.29.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/term v0.3.0 h1:qoo4akIqOcDME5bhc/NgxUdovd6BSS2uMsVjB56q1xI=
+golang.org/x/term v0.3.0/go.mod h1:q750SLmJuPmVoN1blW3UFBPREJfb1KmY3vwxfr+nFDA=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20200902074654-038fdea0a05b/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=