Document CLI authentication precedence and dedicated credentials - #613
Document CLI authentication precedence and dedicated credentials#613kriszyp wants to merge 2 commits into
Conversation
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-613 This preview will update automatically when you push new commits. |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation to reflect the new CLI authentication precedence and dedicated authentication parameters (auth_username and auth_password) introduced in version 5.2.0. This includes updates to the CLI authentication guide, CLI overview, applications component reference, and the v5.2 release notes. There are no review comments, so I have no feedback to provide.
Addresses review feedback from cb1kenobi on PR #613 — items 3 and 4 were bare variable names without stating they're environment variables. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-613 This preview will update automatically when you push new commits. |
Ethan-Arrowood
left a comment
Ethan-Arrowood
left a comment
There was a problem hiding this comment.
I traced every precedence claim in this page against bin/cliOperations.ts on harper main — the ordering, the pre-5.2 behavior note, the auth_-parameter semantics, and the stale-token troubleshooting are all accurate. Nice page.
One substantive problem, inline: the percent-encoding advice for target-URL credentials describes behavior the CLI doesn't have today, so following it produces auth failures rather than fixing them. That's really an upstream harper bug, not just a docs wording issue — flagging it here because the sentence should either come out or be replaced with a limitation note until harper decodes userinfo.
sent with Claude Opus 5
| target=https://username:password@server.example.com:9925 | ||
| ``` | ||
|
|
||
| Percent-encode reserved characters in either value (`@` becomes `%40`, for example). Avoid this form when possible: the URL can be exposed in shell history and process listings, and `harper login` can save its target to the project `.env` file. Prefer environment variables or a saved login for routine use. |
There was a problem hiding this comment.
This advice can't work against current harper main. WHATWG URL getters return userinfo still percent-encoded — new URL('https://admin:p%40ss@host').password === 'p%40ss', and a raw @ gets re-encoded the same way — and the CLI feeds parsedTarget.username/password verbatim into the Basic header (cliOperations.ts:399 → basicAuthHeader) with no decodeURIComponent anywhere; normalizeTarget preserves the encoding too.
So a real password p@ss goes out as p%40ss and authentication fails — encoded or not, the URL form simply can't carry reserved-character passwords right now. I verified the URL behavior with Node directly. harper#1873's tests don't cover encoded userinfo.
Two ways forward: harper decodes userinfo the way curl does (feasible before 5.2 ships), or this sentence is replaced with an explicit limitation note scoping the URL form to reserved-character-free credentials. Either way it shouldn't ship as-is.
|
|
||
| # The environment variables authenticate the admin; username/password remain payload fields. | ||
| # NEW_USER_PASSWORD is provided by a secret manager. | ||
| harper add_user \ |
There was a problem hiding this comment.
Small hardening thought: the auth credentials here are properly protected, but the new user's password= still lands in argv — "$NEW_USER_PASSWORD" keeps it out of shell history, yet the expanded value is visible in process listings. That's inherent to CLI add_user rather than anything this PR introduces, but since this page is the security guidance, a one-line caveat under these examples would keep it airtight.
3 participants
Documents the dedicated
auth_username=/auth_password=parameters and revised CLI credential precedence from HarperFast/harper#1873, including atomic environment-variable pairs, CI/CD user-management examples, application deployment guidance, and stale-token recovery. Also adds the Harper 5.2 release-note entry and replaces the applications guide's legacy credential example.Refs HarperFast/harper#1872.
Generated with Codex (GPT-5).