@hardfin/cli 0.0.2-dev.7 → 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
 
@@ -31,6 +31,7 @@ Most commands are generated from the published API document rather than written
 | `hardfin api` | A call to any endpoint, written by hand, and the escape hatch when no generated command fits |
 | `src/command/surface.generated.ts` | Every endpoint as a command, rewritten by the generator |
 | `surface-overrides.json` | The operations whose generated name is wrong |
+| `spec/core.openapi.yaml` | The API document the generator reads, vendored here |
 | `scripts/generate-surface.mjs` | The generator |
 
 ### How an endpoint becomes a command
@@ -70,20 +71,123 @@ Settle it in `surface-overrides.json`, keyed by `operationId`:
 An override for an `operationId` the document no longer publishes fails the generator. That
 is deliberate, because a silently dropped override renames a command nobody meant to rename.
 
-### Regenerating
+### The vendored document
 
-The Surface workflow runs each weekday, reads `reference/core.openapi.yaml` from the
-`hardfinhq/api-spec` repository through a read-only deploy key, and opens a pull request when
-the generated file changes. It needs the `API_SPEC_READ_DEPLOY_KEY` secret.
+`spec/core.openapi.yaml` is the API document this repository carries, and the generator
+reads it. Nothing fetches a document during a build, a release, or CI.
 
-Run it by hand against a local document:
+Refresh it with the script, which then rewrites the generated commands:
 
 ```sh
-npm run generate-surface -- ../api-spec/reference/core.openapi.yaml
+scripts/update-spec.sh              # reads hardfinhq/api-spec over your own git access
+scripts/update-spec.sh ../hardfin   # bundles the fragmented source in a monorepo checkout
 ```
 
-The document is bundled, meaning its external files are inlined, but `$ref` pointers within
-it remain. The generator follows those pointers itself.
+The monorepo form runs the same bundler at the same version CI uses, so the result matches
+what the api-spec bridge publishes. Commit the document and the generated commands together.
+
+Two checks keep the pair honest.
+
+| Check | Refuses |
+| --- | --- |
+| The generator | a document whose `info.version` is not a date, which means an earlier release |
+| CI | a vendored document that was updated without regenerating the commands |
+
+The first one matters because `hardfinhq/api-spec` can sit a release behind the monorepo
+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
 
@@ -105,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.