Repository navigation
Description
Follow-up to epic #1250. Design agreed 2026-09-06; starts after that epic is released.
After #1250 the web creates accounts only through ORCID OAuth, while the CLI still creates them with a password and a typed, unverified ORCID iD. Two creation paths with different identity roots is what produced the null-username accounts and the duplicate account that epic cleaned up. Phase 9 of #1250 closes the immediate hole by gating the upload access request on a verified iD; this epic removes the second path.
Design
CLI identity becomes ORCID OAuth and the API key becomes plumbing the CLI manages. Use the device authorization flow (RFC 8628), the pattern gh auth login uses, because a terminal cannot receive an OAuth redirect and many users run the CLI on headless hosts:
nemar auth login(signup is the same command) asks the backend for a device code and prints a short user code plus a URL on nemar.org.- The user opens the URL on any browser, signs in with ORCID exactly as on the web today, and confirms "authorize the NEMAR CLI on this machine". A new ORCID creates the pending account through the existing web path; an existing one signs in.
- The CLI polls, receives the API key, and writes it to the config file itself. The user never sees a key or types a password.
Signup then drops the password prompt and the typed ORCID prompt, and collects only the CLI-specific fields: username (auto-suggested, ADR 0042), GitHub handle, city, country, reason. nemar auth key stays for scripts and CI. Password login survives one release as a fallback, then goes. The API key revocation cascade is untouched. Reuse the signed-intent pattern from Phase 7 (ADR 0044) for the device code table and rate limits.
Service accounts are an explicit account kind, not a backdoor or a default ORCID: an ORCID iD identifies a person, the one-person-one-account invariant (ADR 0043) and the unique index on orcid would both break on a shared placeholder, and a bypass is exactly what the tiering exists to remove. A service kind is exempt from the ORCID gap, cannot use the device flow, and gets its keys minted by an owner through nemar admin. Production candidates today: nemarOwner (id 14), nemarAdmin (id 15), test-admin (id 7), none of which has an ORCID; yahya and arnodelorme are person accounts with verified iDs.
Phases
- Backend: device code table,
POST /auth/device/start,POST /auth/device/token(polling, rate limited, single use, short TTL), account creation through the existing ORCID callback, audit rows. - Website: the authorize page (
/cli/authorize?code=...) behind ORCID sign-in, with the confirm step naming the account and the machine. - CLI:
auth loginandauth signupon the device flow, key written to config, password prompt removed from signup,--passwordfallback kept for one release,auth statusand docs updated. - Service-account kind: migration, gap exemption, device flow refusal, owner-only key minting, migrate the three operational accounts.
- Docs on docs.nemar.org and the deprecation notice for password login.
Headless hosts and the paste-key fallback
The device flow is the primary path everywhere, including headless hosts: the CLI prints the URL and a short code or phrase, the user completes ORCID sign-in and the confirm step on any device, and the CLI polls. No browser is ever required on the machine running the CLI.
A second, explicit fallback exists for machines where even polling is impractical (no outbound HTTPS from the login node, air-gapped transfer hosts, an automation account): nemar auth login --remote (name to be settled in phase 3) accepts a key pasted from the web. The key is minted on nemar.org under Settings ("Generate a CLI key", shown once, named after the machine, revocable from the same page), and the CLI writes it to the config file and verifies it with one /users/me call before saving. The paste path is the only way a user ever sees a key; it is never the default prompt.
Coverage target: 90-10, not 80-20
Design and test the flow end to end for the cases below before calling any phase done, rather than shipping the happy path and patching the rest:
- device code expiry, single use, and reuse after expiry; polling with
authorization_pendingandslow_downbackoff, and what the CLI prints while waiting - the user denies on the authorize page, closes the tab, or signs in with a different ORCID than expected; the confirm step names the account and the machine
- the account is
pending,revoked, flaggedidentity_conflict, or a service account at authorize time (each refused with a typed reason the CLI renders) - network loss mid-poll, a second
nemar auth loginwhile one is pending, and Ctrl-C leaving no half-written config - several machines per person: keys are named and listed, revoking one does not revoke the others, and
nemar auth logoutrevokes only its own key - key rotation and the revocation cascade (API key, GitHub PAT, S3 credentials) unchanged in effect
- config file permissions (0600) and an existing config with a password-era key migrating in place
- existing password users: first device-flow login binds to the same account by ORCID or verified email, never creating a duplicate (ADR 0043)
- rate limits on start and token endpoints, audit rows for start, confirm, deny, and expiry
- CI and scripts keep
nemar auth keyand the paste path; documented on docs.nemar.org - the CLI on a machine with a clock far off, and on Windows paths for the config file
Resolved question: Coolvibers
cool-vibers (production user 12) is Yahya's own regular-user test identity: a real person, role member, approved with upload access, no ORCID. It shows the third account kind the design needs. Once sign-in is ORCID-first, one person has one ORCID and Yahya's is bound to yahya, so a non-owner test persona can never sign in through ORCID.
Account kinds are therefore person (default; ORCID-first), service (automation: nemarOwner, nemarAdmin, test-admin), and test (a human's secondary persona: cool-vibers, test-user, test-pending, test-verified, test-revoked). Both non-person kinds are ORCID-exempt, created and keyed by an owner, refused by the device flow, and sign in only through the paste-key path. A test account gets the ordinary member experience (sandbox, upload access request, approval) but on production may own only xx sandbox datasets, enforced at dataset creation, so a real DOI never attaches to a persona. On staging there is no such restriction. Phase 4 above covers all three kinds.
Activity
neuromechanist commentedon Sep 6, 2026
Guiding principle (Yahya, 2026-09-06): the users are not technical, so the easiest and most reliable flow wins over the most flexible one. Judge every phase against this.
What that means for the design above:
nemar auth login, for both first-time signup and later sign-in. No mode flags on the happy path.--remotepaste-key path stays documented for headless edge cases and is never offered in the default prompt.nemar auth loginagain."), never an error code alone.neuromechanist commentedon Sep 6, 2026
Testing strategy (Yahya, 2026-09-06: the ORCID sandbox barely works, so lean on what the web login already taught us)
The ORCID part of the device flow is not new code. The authorize page sits behind the same web session and the same
/auth/orcid/startand/auth/orcid/callbackthat production has run since #569, so every ORCID lesson already in the tree applies unchanged: state cookie verification, the app-host versus api-host cookie model, relink intent minted only by an authenticated same-origin POST (ADR 0022), the one-account invariants (ADR 0043), and the account-bound signed handoff (ADR 0044). What is new never talks to ORCID: the device code table,startandtoken, the confirm step, and key issuance.Three layers, none of which needs the ORCID sandbox:
backend/test/identity-refusals-route.test.tsandcli-self-service-routes.test.tsruns a localBun.serve()that answers/oauth/tokenand the public record API, reached through theORCID_API_BASEandORCID_PUB_API_BASEbindings production already uses. The device flow tests reuse it for the one path that reaches ORCID (a new iD creating the pending account) and seed a web session withPOST /admin/test-fixtures/seed-web-userplus the passwordlessdev_codepath for everything else: start, poll while pending,slow_down, confirm, deny, expiry, reuse, wrong account, pending or revoked or service account at confirm time, second login while one is pending. All at the HTTP entry points.test/auth-gaps-cli.test.tsdoes today: the realnemar auth loginsubprocess against a local stand-in for the device endpoints, covering the printed URL and code, the browser-open attempt, polling and backoff, Ctrl-C leaving no half-written config, the config file permissions, and the--remotepaste path.api-test.nemar.org,test.nemar.org) already carries the production ORCID app credentials with the test callback registered (seebackend/wrangler-sccn.toml, "ORCID SSO on staging uses the PRODUCTION ORCID app, not sandbox"). One walk-through per phase from the two test machines (ssh mcm,ssh mba), including a headless run over ssh where the code is entered on the laptop, is the confidence check; it is the only place real ORCID is in the loop, and it exercises exactly the redirect and cookie behavior that cannot be reproduced locally.Outside references to design against, not to copy blindly: RFC 8628 (device authorization grant) for the code lifecycle and the
authorization_pendingandslow_downresponses, and thegh auth loginflow for the user-facing shape (open the browser with the code pre-filled when one exists, print URL and code otherwise).neuromechanist commentedon Sep 6, 2026
CLI tests are a hard requirement, not a footnote (Yahya, 2026-09-06)
Both CLI test tiers already exist in the tree and the device flow reuses them; a phase is not done until both are green.
Local tier, no network (pattern:
test/auth-gaps-cli.test.ts): spawn the real entry pointbun run src/index.ts auth loginwith an isolatedNEMAR_CONFIG_DIRagainst aBun.serve()that plays the backend'sstartandtokenendpoints, and assert on stdout, the exit code, and the config file on disk. Cases: the printed URL and code; browser-open attempted only when a display is available and never on a headless environment (assert by env); polling withauthorization_pending, thenslow_downhonoured; expiry produces one sentence and a next step; denial produces one sentence and no config write; success writes a 0600 config with the key and a followingnemar auth statusreads it; Ctrl-C (SIGINT to the child mid-poll) leaves the previous config byte-identical; a secondauth loginwhile one is pending;--remotepaste path with an invalid key refused before anything is written; an existing password-era config migrated in place.Live tier against staging (pattern:
runCli(intest/admin-approve-tier-cli.test.ts, gated byTEST_API_URLandtest/.env.test): the real CLI againstapi-test.nemar.org, with the browser side played by the test itself through a seeded web session (POST /admin/test-fixtures/seed-web-user, then the passwordlessdev_codesign-in, both non-production only) posting the confirm step for the code the CLI printed. That proves the whole loop end to end with real D1, real rate limits, and real key issuance, and still never touches ORCID. Also: confirm as apendingaccount, as arevokedaccount, and as a service account, each refused with the typed reason the CLI renders.The only thing left to a human is the one staging walk-through with a real ORCID account per phase, recorded on the phase issue.
Phase 3: CLI login and signup on the device flow (#1289)
feat: typed refusals for the kind route
feat: CLI account-kind filter, doctor check, and key-mint hint
fix: distinct log prefix for schema-shaped webSession errors
refactor: close AccountKind types; factor device-auth's liveness check
Phase 4: Account kinds: person, service, test (#1290)
Merge pull request #1291 from nemarOrg/feature/issue-1272-epic-orcid-…
neuromechanist commentedon Sep 8, 2026
Merged into
devas 0085d0a (PR #1291, regular merge). Phases 1, 3, and 4 landed as PRs #1287, #1289, #1290; phase 2 is nemarOrg/website#317 onstaging; phase 5 is the draft docs PR nemarOrg/docs#23, merged after the release.Next, tracked on the release PR: live-tier run on the dev worker, staging walk-throughs for phases 1 to 4 with a real ORCID account (including a headless
nemar auth login --no-openover SSH), websitestagingtomain, thendevtomainas v0.9.17, then the docs PR. Owner-role live cases need theTEST_OWNER_API_KEYsecret and the seededtest-ownertoken applied to the dev database. #1285 stays open until the docs PR merges.docs: ADR 0049 supersedes 0025 on compute locality
neuromechanist commentedon Sep 8, 2026
Staging walk-through, 2026-09-08 (dev worker at 32f15cc, website
staging)Run from
yahyas-mcm(an admin/owner machine) withTEST_API_URL=https://api-test.nemar.organd an isolatedNEMAR_CONFIG_DIR, the browser side done by a real person with a real ORCID account on test.nemar.org.Phase 1 and 3, device sign-in.
nemar auth login --no-openprinted the linkhttps://test.nemar.org/cli/authorize?code=XXXX-XXXXand the code; on staging the app host is test.nemar.org itself. The first attempt was left unconfirmed and expired after the window: the CLI printed "The code expired. Runnemar auth loginagain for a new one." and exited 1 with nothing written. The second attempt finished on its own the moment the browser confirmed: "Welcome, sshirazi!", owner access, the sandbox reminder, and a config entry with a device-minted key named after the machine (keySource: device, productionapiUrlstored by design).auth status --refreshshows "Key: yahyas-mcm, signed in via browser on 2026-09-08".auth keys listmarks the current key "(this machine)".auth keys create <name>prints the key once with the paste instructions.Paste path and logout semantics. On a second config,
auth login --keysays "Welcome back, sshirazi!" andauth statusshows "Key: pasted key".auth logoutthere keeps the pasted key and says so; the key is still listed from the first machine.auth keys revoke <id>andrevoke currentwork without a prompt; a revoked key answers "Invalid or expired API key" with the re-login hint. On the first machine,auth logoutoutside a TTY refuses the prompt ("Interactive prompt unavailable; use --yes or --no");auth logout --yesrevoked the device key, which then disappeared from the second machine'skeys list.Phase 4, account kinds (owner).
admin users --kind serviceliststest-ownerandtest-adminwithKind: service.admin keys create test-owner <name>mints a key shown once with sign-in instructions;admin keys listandadmin keys revoke test-owner <id>work.admin keys create test-web(a person) is refused with the contract sentence andperson_account.admin kind test-web testthenadmin kind test-web personboth succeed and report the from/to kinds.admin kind <self> serviceis refused: "You cannot change your own account kind."admin doctor kindsreportsnemarOwner,nemarAdmin,cool-vibersabsent on dev (expected there; #1298).Follow-ups filed: #1298 (doctor kinds: absent accounts as informational), #1299 (expiry message should not suggest a bug report). The live tier's three failures on dev are being fixed separately (PR to follow).
Not covered here: a from-scratch ORCID signup (
nemar auth signupwith a never-seen ORCID iD) and the service-account device refusal, which needs a service account with a web session; both remain unit-tested only.fix: passwordless live test premises (#1317)
neuromechanist commentedon Sep 8, 2026
Released as v0.10.0 (2026-09-08)
main(8b088bb), taggedv0.10.0on cf42549, published to npm (0.10.0), production deployed with migrations 0081 and 0082 applied;devsynced to 0.10.1-dev0.app.nemar.org/cli/authorizelive.nemar admin doctor kindson production reports nemarAdmin, nemarOwner, test-admin asservicewith the only finding being the dev-onlytest-ownerabsent (admin doctor kinds: report an absent operational account as informational #1298); the CI onboarding login was verified compatible (onboard-openneuro: nemar auth login --yes nemarDatasets/.github#107 adds--yesas a precaution).neuromechanist commentedon Sep 8, 2026
Post-deploy on production (2026-09-08): a headless
nemar auth login --no-openconfirmed from a phone landed on the real account ("Welcome, yahya!"), the machine-named key appeared next to the password-era key and was revoked afterwards;admin doctor kindsreports the operational accounts as service; the announcement went to the 11 approved accounts (broadcast 3). One transient/users/merefresh failure right after the mint is tracked separately.docs: ADR 0049 supersedes 0025 on compute locality (#1292)