Skip to content

Epic: ORCID-first CLI sign-in and service accounts #1272

Closed
5 of 5 issues completed
Closed

Description

@neuromechanist

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:

  1. 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.
  2. 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.
  3. 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

  1. 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.
  2. Website: the authorize page (/cli/authorize?code=...) behind ORCID sign-in, with the confirm step naming the account and the machine.
  3. CLI: auth login and auth signup on the device flow, key written to config, password prompt removed from signup, --password fallback kept for one release, auth status and docs updated.
  4. Service-account kind: migration, gap exemption, device flow refusal, owner-only key minting, migrate the three operational accounts.
  5. 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_pending and slow_down backoff, 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, flagged identity_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 login while 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 logout revokes 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 key and 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

  1. neuromechanist commented on Sep 6, 2026

    @neuromechanist
    ContributorAuthor

    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:

    • One command, nemar auth login, for both first-time signup and later sign-in. No mode flags on the happy path.
    • When a browser is available on the machine, the CLI opens it itself with the code already in the URL, so the user only sees the ORCID sign-in they already know and one "Authorize" button. The printed URL and code are the fallback for headless hosts, not the default experience.
    • The CLI waits and finishes on its own; no key is shown, copied, or pasted in the default path. The --remote paste-key path stays documented for headless edge cases and is never offered in the default prompt.
    • Every failure has one plain sentence and one next step ("The code expired. Run nemar auth login again."), never an error code alone.
    • Reliability over cleverness: fixed short polling with backoff, generous code lifetime (10 minutes), and the confirm page names the account so a wrong-account sign-in is caught before a key is issued.
  2. neuromechanist commented on Sep 6, 2026

    @neuromechanist
    ContributorAuthor

    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/start and /auth/orcid/callback that 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, start and token, the confirm step, and key issuance.

    Three layers, none of which needs the ORCID sandbox:

    1. Backend route tests, no mocks. The existing pattern in backend/test/identity-refusals-route.test.ts and cli-self-service-routes.test.ts runs a local Bun.serve() that answers /oauth/token and the public record API, reached through the ORCID_API_BASE and ORCID_PUB_API_BASE bindings 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 with POST /admin/test-fixtures/seed-web-user plus the passwordless dev_code path 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.
    2. CLI tests against a local server, as test/auth-gaps-cli.test.ts does today: the real nemar auth login subprocess 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 --remote paste path.
    3. Manual end to end on staging with a real ORCID account. Staging (api-test.nemar.org, test.nemar.org) already carries the production ORCID app credentials with the test callback registered (see backend/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_pending and slow_down responses, and the gh auth login flow for the user-facing shape (open the browser with the code pre-filled when one exists, print URL and code otherwise).

  3. neuromechanist commented on Sep 6, 2026

    @neuromechanist
    ContributorAuthor

    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 point bun run src/index.ts auth login with an isolated NEMAR_CONFIG_DIR against a Bun.serve() that plays the backend's start and token endpoints, 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 with authorization_pending, then slow_down honoured; 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 following nemar auth status reads it; Ctrl-C (SIGINT to the child mid-poll) leaves the previous config byte-identical; a second auth login while one is pending; --remote paste path with an invalid key refused before anything is written; an existing password-era config migrated in place.

    Live tier against staging (pattern: runCli( in test/admin-approve-tier-cli.test.ts, gated by TEST_API_URL and test/.env.test): the real CLI against api-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 passwordless dev_code sign-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 a pending account, as a revoked account, 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.

  4. neuromechanist commented on Sep 8, 2026

    @neuromechanist
    ContributorAuthor

    Merged into dev as 0085d0a (PR #1291, regular merge). Phases 1, 3, and 4 landed as PRs #1287, #1289, #1290; phase 2 is nemarOrg/website#317 on staging; 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-open over SSH), website staging to main, then dev to main as v0.9.17, then the docs PR. Owner-role live cases need the TEST_OWNER_API_KEY secret and the seeded test-owner token applied to the dev database. #1285 stays open until the docs PR merges.

  5. neuromechanist commented on Sep 8, 2026

    @neuromechanist
    ContributorAuthor

    Staging walk-through, 2026-09-08 (dev worker at 32f15cc, website staging)

    Run from yahyas-mcm (an admin/owner machine) with TEST_API_URL=https://api-test.nemar.org and an isolated NEMAR_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-open printed the link https://test.nemar.org/cli/authorize?code=XXXX-XXXX and 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. Run nemar auth login again 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, production apiUrl stored by design). auth status --refresh shows "Key: yahyas-mcm, signed in via browser on 2026-09-08". auth keys list marks 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 --key says "Welcome back, sshirazi!" and auth status shows "Key: pasted key". auth logout there keeps the pasted key and says so; the key is still listed from the first machine. auth keys revoke <id> and revoke current work without a prompt; a revoked key answers "Invalid or expired API key" with the re-login hint. On the first machine, auth logout outside a TTY refuses the prompt ("Interactive prompt unavailable; use --yes or --no"); auth logout --yes revoked the device key, which then disappeared from the second machine's keys list.

    Phase 4, account kinds (owner). admin users --kind service lists test-owner and test-admin with Kind: service. admin keys create test-owner <name> mints a key shown once with sign-in instructions; admin keys list and admin keys revoke test-owner <id> work. admin keys create test-web (a person) is refused with the contract sentence and person_account. admin kind test-web test then admin kind test-web person both succeed and report the from/to kinds. admin kind <self> service is refused: "You cannot change your own account kind." admin doctor kinds reports nemarOwner, nemarAdmin, cool-vibers absent 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 signup with 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.

  6. neuromechanist commented on Sep 8, 2026

    @neuromechanist
    ContributorAuthor

    Released as v0.10.0 (2026-09-08)

  7. neuromechanist commented on Sep 8, 2026

    @neuromechanist
    ContributorAuthor

    Post-deploy on production (2026-09-08): a headless nemar auth login --no-open confirmed 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 kinds reports the operational accounts as service; the announcement went to the 11 approved accounts (broadcast 3). One transient /users/me refresh failure right after the mint is tracked separately.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    featureNew feature or enhancement

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions