feat: cache role credentials in files, keep only the session in the keyring

.env.staging

@@ -11,3 +11,4 @@
 export SOURCE_OIDC_ISSUER=https://auth.staging.source.coop
 export SOURCE_OIDC_CLIENT_ID=a79c9537-be78-454a-9ea1-b96a1be811cc
 export SOURCE_PROXY_URL=https://data.staging.source.coop
+export SOURCE_API_AUDIENCE=https://staging.source.coop

README.md

@@ -125,13 +125,34 @@ credential_process = source-coop creds --role-arn admin-role
 endpoint_url = https://data.source.coop
 ```
 
+### Multiple environments (e.g. staging)
+
+Each proxy host is its own environment, with its own login session and credentials, so production and staging logins live side by side:
+
+```bash
+source-coop login
+( source .env.staging && source-coop login )
+```
+
+`creds` and `auth token` read `SOURCE_PROXY_URL` (or `--proxy-url`) to pick the environment, and without either they use production. A non-production profile must pass `--proxy-url`; one that relied on whichever environment was logged in last will now get production credentials:
+
+```ini
+[profile source-coop]
+credential_process = source-coop creds
+endpoint_url = https://data.source.coop
+
+[profile source-coop-staging]
+credential_process = source-coop creds --proxy-url https://data.staging.source.coop
+endpoint_url = https://data.staging.source.coop
+```
+
 ### Login options
 
 | Flag | Env var | Default | Description |
 |------|---------|---------|-------------|
 | `--issuer` | `SOURCE_OIDC_ISSUER` | `https://auth.source.coop` | OIDC issuer URL |
 | `--client-id` | `SOURCE_OIDC_CLIENT_ID` | `d037d00b-...` | OAuth2 client ID |
-| `--proxy-url` | `SOURCE_PROXY_URL` | `https://data.source.coop` | S3 proxy URL for STS |
+| `--proxy-url` | `SOURCE_PROXY_URL` | `https://data.source.coop` | S3 proxy URL for STS; also selects the environment the login is cached under |
 | `--role-arn` | `SOURCE_ROLE_ARN` | `source-coop-user` | Role ARN to assume |
 | `--format` | | `credential-process` | Output format: `credential-process`, `env`, or `aws-credentials` |
 | `--profile` | | `source-coop` | Profile name for `--format aws-credentials` |
@@ -180,29 +201,31 @@ Use `--profile` to change the section name.
 
 The CLI caches the login session (the Ory refresh, ID and access tokens) and the temporary STS credentials for each role, so that `creds` and API commands work without re-authenticating. The refresh token is kept in the session only: it rotates on use, so every role and every API call refreshes through it, one at a time.
 
-### OS keyring (default)
+### Login session: OS keyring
 
-Credentials are stored in the OS-native keyring under the service name `source-coop-cli`, keyed by role ARN, with the session under `@session`:
+The session, which holds the long-lived refresh token, is stored in the OS-native keyring under the service name `source-coop-cli` and the account `@session`. Other environments prefix it with their proxy host (e.g. `data.staging.source.coop/@session`):
 
 | Platform | Backend |
 |----------|---------|
 | macOS | Keychain (`security` / Keychain Access) |
 | Windows | Credential Manager |
 | Linux | Secret Service API (GNOME Keyring, KDE Wallet) via D-Bus |
 
-### File fallback
+When the OS keyring is unavailable (headless servers, containers, CI), the session falls back to a file, `source-coop/session.json` in the OS cache directory. The fallback is automatic; no configuration is needed.
+
+### Role credentials: cache files
 
-When the OS keyring is unavailable (headless servers, containers, CI), the CLI falls back to JSON files in the OS cache directory with `0600` permissions on Unix:
+Each role's STS credentials are short-lived and re-created from the session, so they're kept in JSON files in the OS cache directory (with `0600` permissions on Unix) rather than the keyring, much like the AWS CLI's own `~/.aws/cli/cache`. A `creds` call that finds fresh credentials doesn't touch the keyring at all, which matters on macOS: after every CLI upgrade, the Keychain asks for your password once for each entry it holds.
 
 | Platform | Path |
 |----------|------|
 | macOS | `~/Library/Caches/source-coop/credentials/<role>.json` |
 | Linux | `~/.cache/source-coop/credentials/<role>.json` |
 | Windows | `%LocalAppData%\source-coop\credentials\<role>.json` |
 
-The session sits beside them, at `source-coop/session.json`.
+Other environments keep the same layout under `source-coop/env/<host>/`, or `source-coop/env/<host>/<port>/` for a non-default port (e.g. `source-coop/env/data.staging.source.coop/credentials/_default.json`).
 
-The fallback is automatic — no configuration is needed.
+Credentials cached in the keyring by earlier versions are still read, so upgrading doesn't log you out; the next `login` replaces them with a file. An entry from v0.3.0 or earlier that carries its own refresh token stays in the keyring until then.
 
 ## OIDC provider setup