Document CLI authentication precedence and dedicated credentials - #613
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.
There was a problem hiding this comment.
Corroborating this — I verified it independently and it holds.
extractTargetCredentials (bin/cliCredentials.ts:28) returns WHATWG URL.username/.password, which stay percent-encoded, and resolveTransportCredentials passes them verbatim to basicAuthHeader with no decodeURIComponent anywhere on the path. Confirmed in Node: new URL('https://admin:p%40ss@host').password === 'p%40ss', and a raw @ re-encodes to the same thing.
So a password of p@ss goes out as the literal p%40ss and 401s — following this advice causes the failure it claims to prevent, and not following it fails too.
Either harper decodes userinfo before 5.2 ships, or the sentence becomes a limitation note scoping the URL form to credentials without reserved characters. I'd block on it not shipping as written rather than on which of the two fixes you pick.
|
|
||
| # 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.
🧹 Preview CleanupThe preview deployment for this PR has been removed. |
DavidCockerill
left a comment
DavidCockerill
left a comment
There was a problem hiding this comment.
This covers all three things I asked for on harper#1873 and gets them right — I verified the precedence order, the pair-atomicity rule, the pre-5.2 note and the stale-token entry against cliOperations.ts rather than taking the page's word for it. Good, careful doc.
Requesting changes on two things:
- @Ethan-Arrowood's percent-encoding thread — I've replied there with an independent confirmation. The URL-credentials advice can't work as written, and since this page is where people will copy from, it shouldn't ship in that form.
- The precedence list is missing a rung (thread below): the
HARPER_CLI_OPERATION_TOKEN/HARPER_CLI_REFRESH_TOKENtier sits between #4 and #5, and those vars are documented nowhere else in the repo despite--for-ciprinting one as the CI secret.
Both are small. Happy to re-review quickly.
— Reviewed by DAIvid (Claude Opus 5)
| 2. Credentials embedded in the `target` URL | ||
| 3. `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` environment variables | ||
| 4. Legacy `CLI_TARGET_USERNAME` and `CLI_TARGET_PASSWORD` environment variables | ||
| 5. A token saved by `harper login` |
There was a problem hiding this comment.
The list omits a rung. cliOperations.ts resolves seven tiers: after the four basic-credential sources it reads HARPER_CLI_OPERATION_TOKEN/HARPER_CLI_REFRESH_TOKEN (falling back to the CLI_TARGET_* namespace, chosen as a unit) and only then ~/.harperdb/credentials.json. So the env-token tier sits between your #4 and #5.
These vars are new in 5.2 — origin/v5.1 has no OPERATION_TOKEN — and harper login --for-ci prints HARPER_CLI_REFRESH_TOKEN as the durable CI secret. Yet they appear in zero markdown files in this repo, so this page is the only place a reader would look.
Concretely: a CI runner holding both a refresh token and HARPER_CLI_USERNAME/PASSWORD gets basic auth, not the token, and this list can't tell them that. One extra rung plus a sentence naming the vars closes it.
4 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).