@hardfin/cli 0.0.2-dev.8 → 0.0.2-dev.9

package/README.md

@@ -7,8 +7,8 @@ It is built for people at a terminal and for agents that call Hardfin on their b
 
 ## Status
 
-The CLI is early. `hardfin api` and the generated commands work against an API key, and
-`hardfin login` is not built yet.
+The CLI is early. Signing in works against a Hardfin that publishes an authorization
+server, and every command also accepts an API key.
 
 ## Install
 
@@ -97,6 +97,98 @@ The first one matters because `hardfinhq/api-spec` can sit a release behind the
 while its bridge pull request is open. Generating from that document would replace the
 current commands with an earlier API's.
 
+## Signing in
+
+```sh
+hardfin login     # approve this CLI in a browser
+hardfin status    # what the CLI is configured with and signed in as
+hardfin logout    # forget this machine, and ask Hardfin to revoke it
+```
+
+An API key is still the way to run unattended. `HARDFIN_API_KEY` wins over a stored sign in,
+so CI and an agent sandbox need no browser.
+
+### What login does
+
+1. Reads `/.well-known/oauth-authorization-server` at the API's host, which names every
+   endpoint, including the authorize endpoint on the app host
+2. Opens a loopback listener on `127.0.0.1`, over IPv4, on whatever port the machine hands out
+3. Opens the browser to approve this CLI, with a PKCE challenge and a state value
+4. Prints the URL, and waits at the keyboard as well as on the listener
+5. Checks the state and the `iss` it came back with, then trades the code for tokens
+6. Keeps the refresh token, and nothing else
+
+While it waits, the terminal takes two things.
+
+| Key | Does |
+| --- | --- |
+| `c` | Copies the URL to the clipboard |
+| A pasted value, then enter | Finishes the sign in without the listener |
+
+Paste whichever of these you have: the whole redirect URL from the browser's address bar,
+`code#state`, or the code alone. A browser on another machine never reaches this listener,
+and the redirect it failed to follow is still in the address bar.
+
+On WSL the browser is opened through Windows, by `wslview`, then PowerShell, then
+`explorer.exe`, because `xdg-open` reaches nothing outside the distribution.
+
+The port changes every time, so Hardfin matches a loopback redirect by everything except its
+port, which is what RFC 8252 asks of an authorization server.
+
+### Where the refresh token is kept
+
+| Host | Kept in |
+| --- | --- |
+| macOS, Windows, and Linux with a secret service | the OS keyring |
+| Everything else, including WSL, containers, and agent sandboxes | `$XDG_STATE_HOME/hardfin/credentials.json`, mode 0600 |
+
+`HARDFIN_NO_BROWSER=1` keeps `hardfin login` from opening a tab, which is what a script or a
+headless host wants. `HARDFIN_CREDENTIAL_STORE=file` forces the file. `hardfin status` reports which one holds
+the credential, and where.
+
+Access tokens are never written anywhere. One is fetched when a command needs it and lives
+in that process only, so what sits at rest is revocable with `hardfin logout`.
+
+A credential is filed under the authorization server it came from, so a local build and
+production never share a sign in.
+
+### What it needs configured
+
+Nothing. Hardfin registers this CLI as a first-party client, and its key is the same in every
+environment, so `hardfin login` works out of the box.
+
+| Setting | Holds | Default |
+| --- | --- | --- |
+| `clientId`, or `HARDFIN_CLIENT_ID` | the client this CLI names itself as | the seeded Hardfin CLI client |
+| `issuerUrl`, or `HARDFIN_ISSUER_URL` | the authorization server | the API's host root |
+
+## Diagnosing a problem
+
+`hardfin status` prints everything a support request needs, and is the first thing to send.
+
+```sh
+hardfin status               # for you
+hardfin status --json        # for a support request
+hardfin status --offline     # no network calls at all
+```
+
+| Section | Holds |
+| --- | --- |
+| `cli` | The version, the API version it speaks, Node, and whether a terminal is attached |
+| `host` | The operating system, kernel, build, processor, memory, timezone, shell, and the distribution and WSL details on Linux |
+| `configuration` | Every setting, its value, and the layer it came from |
+| `credential` | Whether you are signed in, where the refresh token is kept, and when it was issued and last renewed |
+| `authorizationServer` | Whether discovery worked, and every endpoint it named |
+| `api` | Whether the API accepted the credential, when the access token expires, and its scopes |
+
+Nothing secret is printed. An API key and a refresh token are each reported as a
+`sha256:` fingerprint, which identifies a credential across two machines without disclosing
+it.
+
+`refreshExpiresAt` is an estimate. Hardfin expires an unused refresh token after 90 days,
+but the token endpoint reports no expiry, so the CLI applies that rule to the date it last
+renewed. The flag `refreshExpiryIsEstimated` says so in the output.
+
 ## Local configuration
 
 A local build reaches a local server without editing code. Four layers supply the same
@@ -117,13 +209,12 @@ An exported variable beats `.env` because Node leaves a variable that is already
 ```json
 {
     "apiUrl": "http://localhost:8080/v2",
-    "auth": { "tokenUrl": "http://localhost:9000/oauth/token" }
+    "clientId": "https://hardfin.com/cli/client.json"
 }
 ```
 
-The authentication endpoints follow `apiUrl`, so pointing at a local server moves the whole
-flow. Name one under `auth` to move only that one. The keys are `apiUrl`, `apiKey`,
-`clientId`, and `auth` holding `authorizeUrl`, `tokenUrl`, `deviceUrl`, and `revokeUrl`.
+The authorization server sits at the API's host, so pointing at a local server moves signing
+in with it. The keys are `apiUrl`, `apiKey`, `clientId`, and `issuerUrl`.
 
 A key the file does not define fails the command with exit code 2. A typo that was silently
 ignored would look like a setting that never applied.