# Design This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them. Write the tool in the language the rest of the tool is in. ## Names Everything is named after the `cli_name` input. With `acme`: the command is `acme`, the token prefix is `acme_cli_`, the environment variable is `ACME_TOKEN`, and the keychain entry is the service `acme` with the account `default`. ## Data model Use the database in the `database` input. | Table | Columns | | --- | --- | | `cli_device_codes` | `id`, `device_code_hash` (unique), `user_code` (unique), `machine_name`, `ip`, `state`, `user_id`, `last_polled_at`, `interval`, `expires_at` | | `cli_tokens` | `id`, `user_id`, `token_hash` (unique), `name`, `kind` (`device` or `manual`), `created_at`, `last_used_at`, `last_used_ip`, `expires_at`, `revoked_at` | `state` is one of `pending`, `approved`, `denied` and `used`. ## The exchange This follows the OAuth 2.0 device authorization grant, RFC 8628. `POST /cli/device` with the machine's name answers: ```json { "device_code": "…", "user_code": "BDFH-KMPR", "verification_uri": "https://app.example/cli", "verification_uri_complete": "https://app.example/cli?code=BDFH-KMPR", "expires_in": 600, "interval": 5 } ``` `POST /cli/token` with the device code answers status 200 with `{ "token": "…", "expires_at": "…" }`, or status 400 with `{ "error": "authorization_pending" }` and the other errors in R3. Rules: - Store device codes and tokens as SHA-256 hashes. They are random and long. - The user code has 20 to the power 8 possible values. That is only safe together with the 10 minute life and the limit on wrong tries. Keep both. - Moving a code from `approved` to `used` and creating the token is one transaction, so two requests cannot both get a token. - `slow_down`: if a request comes less than `interval` seconds after `last_polled_at`, add 5 to `interval` and answer `slow_down`. - The machine's name comes from the tool and can be anything. Show it as a claim, escape it, and cut it to 100 characters. - The approval page changes nothing on `GET`. Approving and refusing are `POST` with the app's usual CSRF protection. ## The tool - Find the keychain through a maintained library for the language. Do not shell out to system commands with the token on the command line. - The fallback file is `credentials.json` in the user's configuration folder, in a folder named after the command, created with permissions `0600` on systems that have them. - Decide "no display" this way: on Linux, neither `DISPLAY` nor `WAYLAND_DISPLAY` is set; anywhere, the variable `SSH_CONNECTION` is set. - Exit codes: 0 for success, 1 for an error, 2 for not signed in, 130 for Ctrl-C. - Take the server's address from one setting, so tests can point the tool at a local server. ## Configuration | Secret | Purpose | | --- | --- | | `DATABASE_URL` | Connection string for the chosen database. | ## Named here - A device code that was already used, or that the server never issued, is answered `invalid_grant`. - The server's address is read from `_SERVER`, where `` is `cli_name` in capitals. - The 32 random bytes of a token are written in base64url, 43 characters. ## What this spec leaves to you Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README.