feat: auth status

README.md

@@ -93,6 +93,29 @@ Credentials are cached on the server (see [File fallback](#file-fallback)), and
 source-coop --version
 ```
 
+### Checking login status
+
+`auth status` shows whether you're logged in and as whom, and when the cached tokens and a role's credentials expire. It works from the cache: nothing is refreshed and nothing is sent over the network. The account is the one `auth login` looked up (through the API at `--api-url`) when you logged in; for a login from before it did, `auth status` says so until you log in again. On a terminal, labels are dim and the login's state is green or red.
+
+```bash
+source-coop auth status
+```
+
+```
+Environment    production (https://data.source.coop)
+Login          logged in
+Account        Anthony Lukach (alukach)
+Profile        https://source.coop/alukach
+Refresh token  renewed 2026-10-13T14:00:00Z (3 hours ago); expires 2026-11-12 (in 29 days)
+ID token       expires 2026-10-13T18:00:00Z
+Access token   for https://source.coop, expires 2026-10-13T18:00:00Z
+Credentials    _default: expire 2026-10-13T18:30:00Z
+```
+
+**How long until you must log in again** is set by the refresh token, which `creds` and API commands use to renew everything else, so the expiries of the ID token, access token and credentials don't force a login. source.coop's login (Ory) issues opaque refresh tokens, and its token response doesn't say how long they last: that's an Ory project setting, and each renewal starts the clock again. So `auth status` shows when the refresh token was last renewed, and when it expires if left unused: an estimate, to the day, assuming a 30-day lifetime (Ory's default). Set `SOURCE_REFRESH_TOKEN_LIFETIME` (e.g. `720h`, `14d`) if the server uses another; it only changes this estimate, since a login can't ask for a lifetime. Where a provider does give an expiry, that's shown instead. A login from before renewals were recorded shows just `yes` until its next renewal or `auth login`. The profile link is on the site the login was for (`https://staging.source.coop` for a staging login).
+
+The keyring can't list its entries, so `auth status` reports on one environment and role. Pass `--proxy-url` and `--role-arn` (or set `SOURCE_PROXY_URL` and `SOURCE_ROLE_ARN`) to check others.
+
 ### Setting credentials on the environment
 
 After logging in, you can export cached credentials as environment variables:
@@ -161,6 +184,7 @@ endpoint_url = https://data.staging.source.coop
 | `--duration` | | | Session duration, e.g. `3600`, `90s`, `5m`, `12h`, `1d` (bare number = seconds) |
 | `--scope` | | `openid offline_access` | OAuth2 scopes (`offline_access` enables automatic refresh in `creds`) |
 | `--audience` | `SOURCE_API_AUDIENCE` | `https://source.coop` | Audience of the access token for the source.coop API; empty to request none |
+| `--api-url` | `SOURCE_API_URL` | `https://source.coop` | source.coop site whose API names the account you logged in as, for `auth status` |
 | `--port` | | `0` (random) | Local callback port |
 | `--no-cache` | | | Skip caching credentials (just print to stdout) |