# Sign-in for a command-line tool ## What this builds Sign-in for a command-line tool that talks to a web app. The person types `acme login`, approves a short code in their browser, and the tool is signed in. No password is ever typed into a terminal. The tool keeps its token in the system keychain and can be signed out from either side. Read `spekkr.inputs.json` first. The command is called `cli_name`; this file writes `acme`. A token lasts `token_days` days. `open_browser` changes R1 and `ci_tokens` decides whether R7 exists. The spec has two halves: routes and pages added to the web app, and the commands in the tool. It needs the web app to know who is signed in. It does not build that. ## Out of scope - Sign-in for anything but the app's own tool. This is not an OAuth server for other people's programs. - The rest of the tool's commands. ## Requirements Each requirement has an id. Tests name the id they cover. ### R1. Start - `acme login` asks the server for a device code and a user code, and prints the address to open and the user code. - The user code is 8 letters from `BCDFGHJKLMNPQRSTVWXZ`, shown as `XXXX-XXXX`. The device code is 32 random bytes and is never shown. - Both stop working after 10 minutes. - If `open_browser` is on, the tool also tries to open the address with the code filled in. With `--no-browser`, or when there is no display, it only prints. - At most 10 sign-ins can be started from one IP address in 10 minutes. Accept when: the printed address opens the approval page, and nothing printed or logged contains the device code. ### R2. Approve - The address leads to a page on the web app. A person who is not signed in signs in first and is brought back. - The page shows the user code, the machine's name as the tool reported it, and the words "Only approve this if you just ran `acme login` yourself." - The person approves or refuses. Either can be done once. - A code typed by hand is accepted in any case, with or without the hyphen. - After 5 wrong codes in a minute from one account or IP address, the page refuses further tries for 10 minutes. Accept when: approving lets the waiting tool sign in as that person, refusing ends it, and the sixth wrong code is refused. ### R3. Wait - The tool asks the server every 5 seconds whether the code was approved. - The answers are `authorization_pending`, `slow_down`, `access_denied`, `expired_token`, or a token. - A tool that asks more often than it was told gets `slow_down` and must add 5 seconds to its wait. - A device code gives a token once. Asking again with it is refused. - The tool stops with a clear message when the code is refused or runs out, and on Ctrl-C. Accept when: each answer leads to the right message and exit code, and a second request with a used device code is refused. ### R4. Tokens - A token is 32 random bytes behind the prefix `acme_cli_`. The server stores only a hash of it. - A token lasts `token_days` days and then stops working. - The web app has a page that lists a person's tokens: machine name, when it was made, when and from where it was last used. Any can be revoked there. - API requests carry the token as `Authorization: Bearer TOKEN`. Accept when: a revoked or expired token gets 401 on its next request, and one person never sees another person's tokens. ### R5. Keep the token on the machine - The tool stores the token in the system's keychain: Keychain on macOS, Credential Manager on Windows, the Secret Service on Linux. - Where there is no keychain, it stores the token in a file in the user's configuration folder, readable by that user alone, and says so once. - The token is never printed, never passed as a command-line argument, and never written to a log. Accept when: after `acme login` the token is in the keychain and in no file, and on a machine without a keychain the file's permissions allow its owner alone. ### R6. Use, check and sign out - `acme whoami` prints the email address of the signed-in person and when the token expires. - Any command that gets 401 prints "Not signed in. Run `acme login`." and exits with code 2. - `acme logout` revokes the token on the server and removes it from the machine. If the server cannot be reached it still removes it from the machine, and says the token may still be valid until it is revoked on the website. Accept when: after `acme logout` the old token gets 401, and with the network down the token is still removed from the machine. ### R7. Tokens for automation Only if `ci_tokens` is on. - A person can make a token on the tokens page, with a name. It is shown once. - When the environment variable `ACME_TOKEN` is set, the tool uses it and ignores the keychain. `acme whoami` says the token came from the environment. - `acme login` refuses to run while the variable is set, and says why. Accept when: with the variable set, commands run as the token's owner without a keychain, and `acme login` refuses. ### R8. Pages - The approval page, the page after approving or refusing, and the tokens page. Accept when: each page works with a keyboard alone and at a 360 pixel wide screen. ## Definition of done - Every acceptance check above has an automated test, and all tests pass. Tests of the tool run against a local server and a stand-in keychain. - A README explains the commands, where the token is kept on each system, and how to run the tests.