Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -168,6 +168,12 @@ give that population a real answer rather than a role check standing in for one.
Admin approval remains the override for everything here (ADR 0040): the gap
blocks the ASK, never the grant.

**Superseded in part by ADR 0048.** Epic #1272 phase 4 replaced this role-based
exemption with `users.account_kind`: `ProfileGapAccount.role` is gone, and the
`orcid_verified` row exempts `service`/`test` kinds instead of `admin`/`owner`
roles. The rest of this ADR — the one matrix, one copy table, one gap function
arrangement — stands unchanged.

**The plumbing this needed is the shape the phase-8 design predicted.** Two
columns onto `ProfileGapAccount` (`role`, and `orcid_verified` promoted from a
set-on modifier to a predicate input), the same two onto the three SELECTs that
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,153 @@
# ADR 0047: CLI sign-in is the device authorization grant

**Status:** accepted
**Date:** 2026-09-06
**Owner:** Seyed Yahya Shirazi

## Context

Epic #1272 makes ORCID the single identity root for NEMAR.
After epic #1250 the web already creates accounts only through ORCID OAuth,
but the CLI still creates them with a password and a typed, unverified ORCID iD.
Two creation paths with two different identity roots produced the null-username and duplicate-account problems that epic #1250 cleaned up.

A terminal cannot receive an OAuth redirect,
and nobody should type an ORCID password into a CLI prompt.
`nemar auth login` therefore needs a way to authenticate that starts in the terminal and finishes in a browser the person already trusts.
`gh auth login` solves the identical problem with the device authorization grant (RFC 8628), a pattern built for exactly this shape:
a CLI mints a short code, a person authorizes it in a browser,
and the CLI polls for the credential once authorization lands.

Phase 1 (#1281) builds the backend half of this flow.
It never talks to ORCID itself:
`lookup`/`confirm`/`deny` sit behind the existing web session and ORCID routes,
so every ORCID lesson already in the tree (ADR 0022, 0043, 0044) applies unchanged.

## Decision

CLI sign-in is the device authorization grant,
layered on top of the existing web ORCID session rather than a new identity path.
The API key is minted only when the CLI collects it at `/auth/device/token`,
never when the browser confirms at `/auth/device/confirm`:
confirm records `user_id` and `status = 'confirmed'` only,
so no plaintext key is ever at rest between the two steps.
Every key is a named row for one machine (`tokens.name` holds the machine name the CLI or the paste-key form supplied),
and a new sign-in never revokes another machine's key --
a laptop and a compute cluster can both hold a live key for the same account at the same time.
The polling secret itself is never stored in the clear:
`device_codes.device_code_hash` holds only its SHA-256 hash, the same function `tokens.api_key_hash` uses,
so a read of the table cannot be turned into a working code.

## Consequences

`POST /auth/device/token` sits OUTSIDE the strict per-IP auth bucket (`AUTH_PATHS`, 10 requests/minute) and rides the generic bucket instead --
in practice `ip` (500/min), since the CLI holds no bearer until it has collected a key --
because the CLI polls it roughly every 5 seconds while waiting, up to ~120 polls across one 10-minute code.
At that cadence 10 polls fit inside the strict bucket's 60-second window and the 11th would trip it, about 50 seconds in.
The route gets its own per-row floor instead:
a poll sooner than 5 seconds after the last STAMPED poll answers `slow_down` without resetting the timer,
so a jittery client is never starved and can never restart its own countdown.

`verification_uri_complete` pre-fills the user code in the URL.
This is the RFC 8628 section 5.4 phishing trade-off, accepted deliberately:
NEMAR's users are researchers, not security engineers,
and the easiest, most reliable flow wins (the epic's guiding principle).
The mitigation is that phase 2's confirm page names the account and the machine before asking anyone to press Authorize --
a person who did not just run `nemar auth login` sees exactly that, and closes the tab.

Confirm extends a near-expiry code by 120 seconds (`expires_at = MAX(expires_at, datetime('now', '+120 seconds'))`),
so a person who authorizes in the closing seconds of the 10-minute window is not told "expired" by the CLI's very next poll.
This is safe because the code is already bound to one account by that point,
and the CLI still has to hold the device secret to collect the key.

`account_revoked` is unreachable at `lookup`/`confirm`/`deny`:
`findSessionByCookieId` already filters revoked accounts out of session resolution,
so a revoked person carries no web session and gets a 401, never this refusal.
It IS reachable at `/auth/device/token`,
for the case where an admin revokes the account between confirm and collect.

`POST /auth/device/deny` records no `user_id` on the `device_codes` row itself:
any signed-in account may deny a pending code,
and the denier is named only on the audit row, not on the table a later confirm/token read would see.

A brand-new ORCID account's `username` is `null` in `/auth/device/token`'s success response:
`refreshNameThenAssignUsername` runs after finalize, behind the response, not before it,
so a CLI collecting a key moments after sign-up may see the field still unset.
Phase 3 must not key config or first-run behavior on `username` alone.

`identity_conflict` refuses a NEW sign-in -- device confirm and the paste-key mint (`POST /auth/keys`) both check it --
while a key minted before the flag was set keeps authenticating.
The account has to clear the conflict (Settings) before it can add another key,
but nothing already issued stops working the moment the flag is set.

The polling endpoint's error body carries two different fields for "why":
`error` is the RFC 8628 code the CLI's retry loop switches on (`authorization_pending`, `slow_down`, `expired_token`, `access_denied`, `invalid_grant`),
and `reason` -- present only on a terminal answer, never on the two "keep polling" ones --
is the more specific refusal code (`account_pending`, `too_many_keys`, ...) a person-facing message reads from.
They disagree on purpose, which is why `reason` is not spelled `code` like every other refusal on this wire.

Every device-flow timestamp is written and compared in SQL (`datetime('now', '+N seconds')`, `julianday` for `expires_in`),
never in JavaScript.
A JS `toISOString()` value compares greater than a same-day SQL `datetime('now')` value at index 10 (`'T' > ' '`),
so mixing the two silently breaks expiry.
This is a pre-existing bug in `auth_codes`, `web_sessions`, and `orcid_link_intents`;
fixing those is out of scope here and gets its own issue after this phase lands.

`confirm-key-regeneration` (the existing settings flow `regenerate-key` sends its email link through) is UNCHANGED by phase 3
and still revokes every key on the account, machine-named or not:
it is a password-era flow being retired, not the phase's own key-management surface, and phase 3 does not extend it.
`nemar auth login`'s device flow and `nemar auth logout` are the scoped replacement --
logout's default only ever revokes the ACTIVE machine's own key, and only when that key's `keySource` is `"device"`;
a pasted or password-era key may be shared with other machines and is kept, not silently killed by a different machine's logout.
`retrieve-key` and `regenerate-key` survive this release, each printing a deprecation sentence before its first prompt,
pointing at `nemar auth login` as the replacement for both.

Phase 3's local config keys an account by `accountKeyFor(user) = username?.trim() || email`,
since a brand-new ORCID account's `username` is `null` at collection time (this decision's own point above).
`upsertAccount` merges a re-login into whatever entry it finds by that key OR by email,
so an account that was stored under its email (no username yet) is found and renamed rather than duplicated the moment the server starts reporting a username --
`dismissedNoticeIds`, `profileGaps`, `orcidVerified`, and `serviceAccess` all survive the merge intact.
A re-login on the SAME machine also mints a new device key every time
(the token endpoint keeps no memory of "this machine already has one"),
so phase 3 best-effort revokes the machine's OWN previous key with the newly collected bearer, after the local config write lands --
never a pasted or password-era key, which by definition is not this machine's alone to kill.
The revoke is attempted even when the preflight probe already found the OLD key dead --
a repeat revoke of an already-gone row is harmless and caught the same way any other failure is --
what that foreknowledge skips is only the "(replaced this machine's previous key)" confirmation line,
since nothing was meaningfully replaced by revoking a key that was already dead.
Left unbounded, a script that re-runs `nemar auth login` would otherwise mint a fresh row per invocation until the `MAX_LIVE_API_KEYS` cap (25).

The CLI's config file now always holds a live API key rather than a password hash on every account it stores,
so `getStore()` writes it `configFileMode: 0o600` (honored by `conf` 13's `atomically` writer regardless of umask)
and migrates an existing file an older build left at `conf`'s default file mode (0o666, unrelated to the conf version) to 0600 on first use, non-Windows only.

## Alternatives considered

- **Mint the key at confirm, encrypted at rest.**
An encrypted key is plaintext-equivalent the moment it needs to be read back for the CLI to collect,
and it adds a second secret (the encryption key) to rotate and protect.
Minting at collect removes the "at rest between steps" window entirely rather than encrypting it.
- **HMAC-signed device state, no table.**
Works for the ORCID CLI-link intent (migration 0078) because that flow is single-use and needs no server-side rate floor.
The device grant needs both: single use (confirm must not be replayable)
and a per-code poll floor (`slow_down`),
neither of which a stateless signed token can enforce on its own.
0078 chose a table for the same reason this phase does.
- **Keep password login for the CLI.**
Rejected by the epic itself:
two identity roots (password + typed ORCID iD vs. verified ORCID OAuth)
is the problem epic #1250 already cleaned up once.

## Receipts

- Epic #1272, issue #1281 (phase 1 backend).
- RFC 8628 (OAuth 2.0 Device Authorization Grant), section 3.5 (error codes)
and section 5.4 (phishing considerations).
- ADR 0022 -- ORCID relink intent is minted only by an authenticated same-origin POST.
- ADR 0040 -- admin approval is the single writer of upload access;
`verified` is the base tier.
- ADR 0043 -- one person, one account.
- ADR 0044 -- identity self-service reaches the CLI, and ORCID does it through the browser.
- Migration 0078 (`orcid_link_intents`) -- the precedent for a short-lived,
single-use table over a stateless signed token.
- Migration 0081 (`device_codes`).
154 changes: 154 additions & 0 deletions .context/decisions/0048-account-kinds-are-explicit.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,154 @@
# ADR 0048: Account kinds are explicit: person, service, test

**Status:** accepted
**Date:** 2026-09-07
**Owner:** Seyed Yahya Shirazi

## Context

Sign-in is now ORCID-first (ADR 0047): the web creates accounts only through ORCID
OAuth, and the CLI obtains its key through the same browser sign-in. ADR 0043's
one-person-one-account invariant and the unique index on `users.orcid` both assume
an ORCID iD identifies exactly one person, and both break the moment a shared
placeholder iD is asked to back more than one account.

Yet three operational accounts (`nemarOwner`, `nemarAdmin`, `test-admin`) hold no
ORCID and never will: nothing signs in to them as a person, so there is nothing to
link. And a person can legitimately need a second, non-person account: Yahya's
regular-user persona `cool-vibers` is a second account for a person whose ORCID is
already bound to `yahya`, and the seeded `test-*` fixtures play the same role in
lower environments.

Before this phase the `orcid_verified` gap in the shared profile-gap matrix
(`shared/contract/profile-gaps.ts`) exempted this population by an interim role
check, `isExemptRole` treating `admin`/`owner` as exempt, documented there as
provisional. A role is a permission level, not a fact about what an account is: a
person who happens to be an admin is not exempt from having a real identity, and an
operational account with no admin role at all (there is none today, but nothing
stopped one) would have had no exemption at all.

## Decision

**`users.account_kind` names what an account IS, not what it may do.** Three
values, `person` (default), `service` (automation; no human signs in to it
directly), `test` (a human's secondary persona: signs in and uploads like a
person, but is barred from real data). Kinds are set only by an owner
(`POST /admin/users/:username/kind`), never inferred from role, email, or
anything else.

**One refusal code covers both non-person kinds.** The device sign-in flow
(`shared/contract/device-auth.ts`) already declared `service_account` for this
population before this phase existed to give it a real answer. Rather than add a
second `test_account` code, `accountRefusal` (backend/src/services/device-auth.ts)
answers `service_account` for either kind: from the CLI's side of `nemar auth
login`, "service" and "test" are the same fact: a human is not meant to sign in
this way, and both the website and the CLI already parse this as a closed enum,
so widening its meaning costs nothing a new code would not also cost. The message
is reworded kind-neutrally ("This is a service or test account...") and still
names the fix: `nemar admin keys create`.

**The ORCID gap exempts by kind, and role leaves the gap matrix entirely.**
`ProfileGapAccount.account_kind` replaces `role`; `isExemptKind` replaces
`isExemptRole`. This is a strictly better predicate than the role check it
replaces: the operational accounts this phase moves to `service` keep their
exemption, and a person who happens to hold `admin`/`owner` is no longer exempt at
all. At the time of writing, the two real owner accounts (`yahya`,
`arnodelorme`) already hold verified iDs, so nothing regresses for them today.
That fact is an observation about the current catalog, not something this
migration or the kind exemption depends on: a future owner without a verified
iD would simply see the `orcid_verified` gap like any other `person`, which is
the fail-closed behavior this decision wants. An absent or unrecognized kind is
not exempt (fails closed, the same posture the role check held).

**Keys for non-person kinds are owner-minted, never self-served.** Self-service
`POST /auth/keys` and the device flow's own mint (`DEVICE_MINT_INSERT_SQL`) both
gain a `person`-only predicate. The mint moves to
`POST /admin/users/:username/keys`, and it runs in the opposite direction from
every other admin user-route: it refuses a `person` target (403 `person_account`)
because a person creates their own keys through sign-in, and it is the only path
that can mint one for `service`/`test`. `GET`/`DELETE` on the same resource work
for any kind: listing and revoking are administrative record-keeping, not a
liveness question.

**A `test` account on production may own only `xx` sandbox datasets.**
`realDatasetCreateGate` (backend/src/services/upload-gate.ts) gains a third input
and refuses a real (`nm`) create with `test_account_sandbox_only` when
`isProduction && !sandbox && account_kind === "test"`. No restriction off
production, and no restriction on a `service` account, deliberately: the
device/key gates above stop a `service`/`test` account only from SELF-serving a
key (self-minting, or the device flow's own sign-in). They say nothing about a
request already carrying a key an owner minted for it through
`POST /admin/users/:username/keys`. That key authenticates through
`authMiddleware` exactly like any other (it never reads `account_kind`), so an
owner-minted `service` key reaches the dataset-create route, and every other
authenticated route, normally. `test_account_sandbox_only` is therefore the one
and only place a `service` account is unrestricted here on purpose: it is what
an operational/automation account is FOR, while `test` stays fenced to `xx`
sandbox datasets on production (#1284 review corrected this section; it
previously and incorrectly claimed a service account could not reach this route
at all).

## Consequences

**A test persona is otherwise a person, on purpose.** Off production, or when
staying inside the `xx` sandbox band, a `test`-kind account can request upload
access, upload, and publish exactly like a `person` account: the kind restricts
where its DOIs can point, not whether it can act. Which EZID shoulder a DOI lands
on is controlled by the admin's own `sandbox` flag at DOI-creation time
(`POST /admin/datasets/:id/doi/concept`), independent of the uploading account's
kind; the sandbox-only dataset-create gate is what keeps a `test` account from
ever reaching a real `nm` dataset to attach a production DOI to in the first
place.

**A persona cannot accidentally collide with its owner's real identity.** If a
`test`-kind account tries to link the same ORCID iD its owner's `person` account
already holds, the attempt is refused the ordinary way: `orcid_in_use`, the
partial unique index migration 0077 built for ADR 0043, not by anything specific
to kind. Kind exempts the account from being ASKED for a verified iD; it does not
weaken the uniqueness the index already enforces if one is offered anyway.

**`test-web` stays a `person`.** It is the shared web-QA account (#1008) that has
to reach the ORCID authorize page and the Settings key form the way a real person
would; moving it to `test` would make it exempt from exactly the flows it exists
to exercise.

**The website does not render kind yet.** `nemarOrg/website#318` tracks showing
it in the admin user list and account settings; out of scope here (ADR 0045's
wire rule already covers it: `account_kind` is optional on `userSchema` and
`adminUserListItemSchema`, absent on `webUserSchema`, so no website change is
forced by this phase).

## Alternatives considered

- **Add a distinct `test_account` refusal code.** Rejected: the CLI's and the
website's actionable response to "you cannot sign in this way" is identical for
both kinds (ask an owner for a key), so a second code would be a distinction
with no behavioral difference on either client, only a wider enum to keep in
sync.
- **Keep the role-based exemption and add kind alongside it.** Rejected: two
predicates that can independently decide "exempt" is exactly the drift ADR 0045
exists to end. Kind is the fact the exemption was always trying to approximate;
once it exists, the role check has nothing left to do.
- **Let a `test` account's DOI shoulder follow its kind automatically.** Rejected:
the shoulder is already an explicit admin decision at DOI-creation time
(ADR 0007), made once per dataset regardless of who uploaded it; teaching kind
to override that would be a second, silent way to pick a shoulder that could
disagree with the explicit one.

## Receipts

- Epic #1272, sub-issue #1284.
- ADR 0043 (one person, one account), ADR 0044 (identity self-service on the
CLI), ADR 0045 (the CLI and the web say one thing about an account: the
`orcid_verified` row's role exemption, now superseded in part by this ADR),
ADR 0047 (CLI sign-in is the device authorization grant).
- `backend/src/db/migrations/0082_account_kind.sql`,
`shared/contract/profile-gaps.ts` (`isExemptKind`),
`shared/contract/device-auth.ts` (`service_account`, `person_account`),
`backend/src/services/device-auth.ts` (`accountRefusal`,
`accountLivenessRefusal`), `backend/src/services/upload-gate.ts`
(`realDatasetCreateGate`), `backend/src/routes/admin/user-keys.ts`.
- `backend/test/account-kind-migration.test.ts`,
`test/profile-gaps-matrix.test.ts`, `backend/test/admin-keys-routes.test.ts`,
`backend/test/admin-kind-route.test.ts`,
`backend/test/dataset-create-test-kind.test.ts`.
Loading
Loading