diff --git a/documentation/declared-differences.md b/documentation/declared-differences.md index c9559171..fccb1a98 100644 --- a/documentation/declared-differences.md +++ b/documentation/declared-differences.md @@ -12,7 +12,7 @@ reports the difference as intended and reports its disappearance as news This page gathers every declared difference into one register. It does not replace the sources: each row links to the place the difference is recorded, -which stays the authority. Compiled 6 Nov 2026, and updated since (SBGN and the website's event PDF, 7 Nov 2026; search, diagram and reaction images, PowerPoint, 8 Nov 2026; the analysis report's comparisons and its routing to pdf-export, 14 Nov 2026). +which stays the authority. Compiled 6 Nov 2026, and updated since (SBGN and the website's event PDF, 7 Nov 2026; search, diagram and reaction images, PowerPoint, 8 Nov 2026; the analysis report's comparisons and its routing to pdf-export, 14 Nov 2026; the ORCID claim, as specified, 17 Nov 2026). **Terms used here** @@ -44,6 +44,7 @@ which stays the authority. Compiled 6 Nov 2026, and updated since (SBGN and the | [ContentService: graph queries and search](#contentservice-graph-queries-and-search) | 4 | Three live on beta, one merged | | [ContentService: reaction layout](#contentservice-reaction-layout) | 4 | Live on beta | | [ContentService: contact form](#contentservice-contact-form) | 7 | Live on beta | +| [ContentService: ORCID claim](#contentservice-orcid-claim) | 12 | Spec only | | [ContentService: images](#contentservice-images) | 14 | Live on beta, but the PowerPoint and the overview's options, merged | | [AnalysisService gateway](#analysisservice-gateway) | 5 | Two live on beta; the report's three merged | | [SBML (sbml-exporter)](#sbml-sbml-exporter) | 13 | Website's SBML live on beta; bulk file not switched | @@ -51,7 +52,7 @@ which stays the authority. Compiled 6 Nov 2026, and updated since (SBGN and the | [SBGN (sbgn-exporter)](#sbgn-sbgn-exporter) | 8 | Website's SBGN merged, routed on beta; bulk file not switched | | [Pathway PDFs (pdf-export spec 001)](#pathway-pdfs-pdf-export-spec-001) | 17 | Website's PDF live on beta; book not switched | | [Analysis report PDF (pdf-export spec 002)](#analysis-report-pdf-pdf-export-spec-002) | 21 | Merged; website routed to it (spec 010 T066), not yet deployed | -| **Total** | **116** | | +| **Total** | **128** | | Then: [things that look like differences but are not](#not-differences), and [decisions still open](#decisions-still-open). @@ -120,6 +121,25 @@ sending, and the message's subject and body are kept. Done on beta on | A rate limit | None of its own | Six requests a minute per client address, with a burst of three, at the web server | Security: each request that passes sends a message | 6 Nov 2026 (D23) | Live on beta | [spec 006 D23](../specs/006-content-service-to-node/research.md), `deploy/nginx` | | Limits on what is sent | Any body the server would read, any field length; an address checked by JavaMail | Body at most 64 KB (413 from the web server and from node); name and subject at most 200 characters, message at most 20,000 (400); the reader's address must be one plain address (no `%`, `!` or encoded word, a domain of two or more labels); header values made one line, and a non-ASCII name written as RFC 2047 words of at most 75 characters | Security: a large body held the service, and a reader's text must not break the message's headers | Review of #836 and #838 (D23, Limits) | Live on beta | [spec 006 D23](../specs/006-content-service-to-node/research.md), #844 | +## ContentService: ORCID claim + +The ORCID endpoints ("Claim your work"). No Java service answers them today: the old website's module did, and a port to the Java ContentService was reverted in May 2026. The maintainer decided on 16 Nov 2026 to port them to node; [spec 031](../specs/031-orcid-claim/spec.md) specifies it, so "Java" here is the old module. The claims keep its paths, body and answer. + +| What | Old module (data-content) | New | Why | Decided | Status | Source | +| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------- | --------- | ----------------------------------------------------------- | +| Sign-in protection | No `state`; the code passed through a page's script to `/orcid/token`; the token kept in the server session | A single-use `state` bound to a cookie (and PKCE if ORCID checks it); the callback exchanges the code on the server; the token kept only in the service's memory, behind an opaque `HttpOnly` cookie, for at most 8 hours | Security | Spec 031 R3, R4, 17 Nov 2026 (for review) | Spec only | [spec 031](../specs/031-orcid-claim/contracts/endpoints.md) | +| `/orcid/token` | Exchanged a code given in the query; `true` | Not served (404): the callback does it | Security: the code never reaches the site | Spec 031 R2 | Spec only | [spec 031](../specs/031-orcid-claim/contracts/endpoints.md) | +| The callback | A page (old site) or a 302 carrying the code to the site (reverted port); at `/content/orcid/callback` (old) or `/ContentService/orcid/callback` (port) | A 302 to `/orcid-callback?outcome=…`, never with the code; served at both addresses | Security, and design: either registered address works | Spec 031 R2, FR-002 | Spec only | [spec 031](../specs/031-orcid-claim/contracts/endpoints.md) | +| Sign-out | GET `/orcid/signout` | POST, from the site's own pages only; the token revoked at ORCID if the open question is so decided. Body still `success` | Security: a GET sign-out can be triggered from another site | Spec 031 FR-010, FR-016 | Spec only | [spec 031](../specs/031-orcid-claim/contracts/endpoints.md) | +| `/orcid/authenticated` | `true` or `false` | `{enabled, signedIn, orcid?, name?}`: the site needs to know whether the feature is on and who is signed in, which the old pages read on the server | Design | Spec 031 R2 | Spec only | [spec 031](../specs/031-orcid-claim/contracts/endpoints.md) | +| `/orcid/{orcid}/works` | ORCID's whole works list, passed through (API v2.1) | Only the works Reactome added, narrowed to `OrcidWork` | Design and privacy: the site needs no more | Spec 031 R7 | Spec only | [spec 031](../specs/031-orcid-claim/contracts/endpoints.md) | +| `/orcid/let-us-know-your-orcid` | A page; in the reverted port, JSON carrying the whole token record and the captcha key | JSON `{title, subject, message}`; the message also names the Person page when given | Security: the token never reaches the browser; the site has its own human check | Spec 031 R2 | Spec only | [spec 031](../specs/031-orcid-claim/contracts/endpoints.md) | +| Errors | 500 for a missing Person, a Person without an iD and a mismatch, naming both iDs; a bare 401; ORCID's own message on its failures | 404, 403, 403, 401, 409, 502, 504 in the old envelope with an `error-code`; no other person's iD, no ORCID text | Design and privacy | Spec 031 contracts/endpoints.md | Spec only | [spec 031](../specs/031-orcid-claim/contracts/endpoints.md) | +| Switching the feature on | On when the machine's name matched a configured one | On exactly when its settings are complete; ORCID's production servers refused without an explicit switch | Design: tests and the test site can never reach production ORCID | Spec 031 R8 | Spec only | [spec 031](../specs/031-orcid-claim/contracts/endpoints.md) | +| Calls to ORCID | Member API v2.1, over a connection that accepted any certificate | Member API v3.0, HTTPS verified by name; the same works, in v3.0's names | Security, and platform: v3.0 is ORCID's current version | Spec 031 R6 | Spec only | [spec 031](../specs/031-orcid-claim/contracts/endpoints.md) | +| What is reported to the report webapp | Each claim's added works, and a record of each sign-in | Each claim's added works only (if the open question is so decided); nothing about sign-ins | Security | Spec 031 R10, FR-023 | Spec only | [spec 031](../specs/031-orcid-claim/contracts/endpoints.md) | +| A rate limit | None of its own | A budget per client address at the web server | Security | Spec 031 R9 | Spec only | [spec 031](../specs/031-orcid-claim/contracts/endpoints.md) | + ## ContentService: images | What | Java | New | Why | Decided | Status | Source | @@ -334,6 +354,9 @@ These show up in comparisons but are not differences in what a reader gets. ## Decisions still open +- **ORCID: revoke at sign-out?** Recommended: yes, so no grant outlives the session ([spec 031](../specs/031-orcid-claim/spec.md) FR-016). +- **ORCID: which Person a sandbox account claims for on the test site.** Recommended: a test-only mapping in the host's private settings, to a Person whose owner agrees (FR-022). +- **ORCID: where claim records go.** Recommended: the report webapp, as before, claims only, never a token (FR-023). - **One mail path for contact messages.** The site's search-page form (its own `/contact` route, sending through the server's local mail program) and the ContentService `POST /contact` (through SES) both stay for now; whether the diff --git a/specs/006-content-service-to-node/tasks.md b/specs/006-content-service-to-node/tasks.md index 8582f550..78ccc5fb 100644 --- a/specs/006-content-service-to-node/tasks.md +++ b/specs/006-content-service-to-node/tasks.md @@ -125,7 +125,7 @@ Found 19 Oct 2026 by comparing every mapping in the Java source with the publish ## Phase 10: Last -- [ ] T110 The ORCID endpoints, `/ContentService/orcid/**` ("Claim your work", #114): about eleven (OAuth login, callback, token, sign-out, authenticated; five claims; `{orcid}/works`; `let-us-know-your-orcid`). Not in the deployed service at all: their source is `org.reactome.server.orcid` in reactome/data-content. They need ORCID OAuth credentials and the report application. Ported last (awright, 15 and 19 Oct 2026), after reviewing ORCID's requirements with awright. +- [ ] T110 The ORCID endpoints, `/ContentService/orcid/**` ("Claim your work", #114): about eleven (OAuth login, callback, token, sign-out, authenticated; five claims; `{orcid}/works`; `let-us-know-your-orcid`). Not in the deployed service at all: their source is `org.reactome.server.orcid` in reactome/data-content. They need ORCID OAuth credentials and the report application. Ported last (awright, 15 and 19 Oct 2026), after reviewing ORCID's requirements with awright. **Specified in [spec 031](../031-orcid-claim/spec.md)** (decided 16 Nov 2026: ported to node, never Java; built against a stub ORCID, then ORCID's sandbox; production later). Its tasks replace this one, which is ticked when spec 031's T028 lands. ## Notes diff --git a/specs/031-orcid-claim/checklists/requirements.md b/specs/031-orcid-claim/checklists/requirements.md new file mode 100644 index 00000000..c6a8f74e --- /dev/null +++ b/specs/031-orcid-claim/checklists/requirements.md @@ -0,0 +1,36 @@ +# Specification Quality Checklist: ORCID "Claim your work" on the node content service + +**Purpose**: Validate specification completeness and quality before proceeding to planning + +**Created**: 2026-11-17 + +**Feature**: [spec.md](../spec.md) + +## Content Quality + +- [x] No implementation details (languages, frameworks, APIs) beyond the protocol the feature is about (OAuth, ORCID's Member API) and the repository's own fixed rules (node, no Java) +- [x] Focused on user value and business needs +- [x] Written for non-technical stakeholders where it can be; the security requirements are necessarily technical +- [x] All mandatory sections completed + +## Requirement Completeness + +- [ ] No [NEEDS CLARIFICATION] markers remain — three remain, for the maintainer (FR-016, FR-022, FR-023), each with a recommendation; T002 resolves them +- [x] Requirements are testable and unambiguous (each maps to a check in contracts/checks.md) +- [x] Success criteria are measurable +- [x] Success criteria are technology-agnostic where they can be +- [x] All acceptance scenarios are defined +- [x] Edge cases are identified +- [x] Scope is clearly bounded (production out of scope) +- [x] Dependencies and assumptions identified + +## Feature Readiness + +- [x] All functional requirements have clear acceptance criteria +- [x] User scenarios cover primary flows +- [x] Feature meets measurable outcomes defined in Success Criteria +- [x] No implementation details leak into specification beyond the above + +## Notes + +- The three open questions do not block building against the stub; they gate the sandbox run (T027) and the parts of T005, T013 and T017 that depend on them. diff --git a/specs/031-orcid-claim/contracts/checks.md b/specs/031-orcid-claim/contracts/checks.md new file mode 100644 index 00000000..fa8d488d --- /dev/null +++ b/specs/031-orcid-claim/contracts/checks.md @@ -0,0 +1,35 @@ +# Contract: the checks, and how each is shown failing + +Constitution III: no check is trusted until it has been seen red. Each row names the breakage that must turn it red; the task that adds the check records, in `tasks.md`, that it did. + +All service checks run in vitest against the stub ORCID (T006) on the loopback interface, with the graph reads replaced as the person specs replace them, and the claim-record sender and the clock injected. Site checks run in Playwright with `/ContentService/orcid/**` answered by the test (`page.route`), the way `e2e/support/backend.ts` answers recordings, and the stub's authorise page. + +| # | Check | Shown failing by | Task | +| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ---- | +| C1 | Login's redirect carries client id, scope `/activities/update`, the configured redirect URI, a fresh `state` (and S256 challenge if R4) | Dropping `state` from the URL | T011 | +| C2 | A callback with a missing, unknown, reused or expired `state` exchanges nothing and creates no session | Skipping the state lookup; skipping the single-use delete; widening the age to 24 hours | T012 | +| C3 | The session identifier changes at sign-in | Reusing the pending sign-in's identifier | T012 | +| C4 | No answer of the family, and no `Location`, carries the token, refresh token or code (scan of every answer in the suite for the stub's token and code strings) | Adding the token to `authenticated`'s answer; passing `code` to `/orcid-callback` | T012 | +| C5 | Login's `return` is used only when it is a path on this site (cases: `//x`, `/\x`, `https://x`, `javascript:`, encoded variants) | Accepting any value starting with `/` | T011 | +| C6 | Cookie attributes: `HttpOnly`, `Secure` off loopback, `SameSite=Lax`, `Path=/` | Removing `HttpOnly` | T009 | +| C7 | Idle 30 minutes, absolute 8 hours: the session is gone (injected clock) | Refreshing the absolute limit on use | T009 | +| C8 | A POST without the site's `Origin` is 403 and reaches neither the graph nor ORCID | Removing the origin check from the claim handler | T013 | +| C9 | A claim for a Person whose iD is not the session's, or who has none, is 403, and the stub receives nothing | Comparing with the request's iD instead of the session's | T015 | +| C10 | `all` sends an event both authored and reviewed once, as both; batches are at most 100; 250 works make 3 requests | Removing the intersection; batching at 101 | T015 | +| C11 | Each work matches [orcid-works.md](orcid-works.md) (the stub validates the body against it) | Changing `other-id` to `other_id`; giving a reaction a DOI | T014 | +| C12 | The summary's five counts equal the stub's tallies, conflicts included | Counting a 409 as an error | T015 | +| C13 | ORCID's 401 mid-claim ends the session and answers 401; a 500 or timeout mid-claim answers 502 naming how many were added | Swallowing the 401; answering 200 with partial counts | T015 | +| C14 | A second claim on the same session while one runs is 409 | Removing the per-session lock | T015 | +| C15 | Sign-out is POST only, deletes the session, clears the cookie, and calls the stub's revoke (if FR-016 is decided so) | Leaving the session in the store | T013 | +| C16 | Disabled (no settings; production addresses without the switch): `authenticated` says `enabled:false`, every other route 404 | Treating a missing secret as enabled | T005 | +| C17 | No test reaches ORCID: the service's ORCID client refuses any host but the configured one, and the test settings name only the loopback stub | Pointing a test at `sandbox.orcid.org` (it must fail without a network request) | T008 | +| C18 | The service's log lines from the whole ORCID suite contain none of: the stub's token, refresh token, code, `state`, session id, client secret, the stub account's iD and name | Logging the token exchange's answer | T016 | +| C19 | A claim records one claim record per added work, with the data-model's fields and no token; a record-store failure leaves the answer unchanged | Sending a sign-in record as the old module did; awaiting the store | T017 | +| C20 | `let-us-know-your-orcid` carries the session's iD and the Person page's address, and nothing else of the session | Returning the session object | T018 | +| C21 | `works` returns only Reactome-sourced works, narrowed to `OrcidWork` | Passing ORCID's answer through | T019 | +| C22 | Every answer has `Cache-Control: no-store`; the callback has `Referrer-Policy: no-referrer` | Removing the header from one route | T009 | +| C23 | nginx and the dev proxy agree on the two ORCID routes; the callback locations log no query string; `nginx -t` passes | Removing the dev proxy's callback entry | T020 | +| C24 | Site: signed out, the Person page shows "Sign in with ORCID"; signed in as the page's person, the claim buttons; as another, "Let us know your ORCID"; disabled, nothing | Showing the claim buttons on any signed-in page | T022 | +| C25 | Site: `/orcid-callback` shows each outcome's words and returns to the `return` path only when it is a site path | Navigating to `return` unchecked | T021 | +| C26 | Site: a claim's confirmation states the count; the summary shows the four counts; a 401 offers sign-in again | Ignoring the 401 | T023 | +| C27 | Fixtures and recordings hold only placeholder people and the stub's or ORCID's example iDs (a check over `tools/content-node/fixtures/orcid*` and `e2e/**/orcid*`) | Adding an iD that is not on the allowlist | T007 | diff --git a/specs/031-orcid-claim/contracts/endpoints.md b/specs/031-orcid-claim/contracts/endpoints.md new file mode 100644 index 00000000..e042949a --- /dev/null +++ b/specs/031-orcid-claim/contracts/endpoints.md @@ -0,0 +1,108 @@ +# Contract: the ORCID endpoints + +Every path is under `/ContentService` unless it starts with `/content`, and each takes a trailing slash. "Old" is data-content's `org.reactome.server.orcid` package as read on 17 Nov 2026 (the May 2026 ContentService port, reverted, differed only where noted). Nothing serves any of them today, so every change below is a declared difference (rows in `documentation/declared-differences.md`, added with this spec), not a parity break. + +**The family's error envelope** is the old module's `ResponseError`, all five keys always written: + +```json +{ + "response-code": "403", + "developer-message": null, + "user-message": "You can claim works only on your own Person page.", + "error-code": "orcid.person-mismatch", + "more-info": null +} +``` + +Old: `user-message` only, the other four `null`, from `GlobalExceptionHandler.toJsonResponse`; a missing session was a bare 401 with no body. New: `response-code` is the status, `error-code` is one of the codes below, and the 401 has the envelope too. The type is `OrcidError` in `projects/contract/orcid.ts`. + +**Every answer** carries `Cache-Control: no-store`. + +## Summary table + +| # | Method, path | Old | New | Same shape? | +| --- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | +| 1 | GET `/orcid/login` | 302 to ORCID authorise; no `state`; redirect URI built from the request's host (https only on the production host) | 302 to ORCID authorise with `state` (and PKCE, R4); redirect URI from settings; optional `?return=` | Same (302); new inputs | +| 2 | GET `/orcid/callback`, GET `/content/orcid/callback` | Old: a page that called `/orcid/token?code=…` from script, then closed its popup. Reverted port: 302 to `/orcid-callback?ok=true&code=…` | Checks `state`, exchanges the code on the server, creates the session, 302 to `/orcid-callback?outcome=signed-in&return=…` (or `outcome=declined` / `outcome=failed`); the code never leaves the server | Changed (security) | +| 3 | GET `/orcid/token?code=` | Exchanged the code; set the session; `true`, or 401 with ORCID's error description | **Not served** (404): folded into the callback | Retired (security) | +| 4 | GET `/orcid/signout` | Invalidated the session; `success` (text) | **POST** `/orcid/signout`, same-origin only; deletes the session, clears the cookie, revokes the token (FR-016); 200 `success` (text). GET answers 405 | Same body; method POST | +| 5 | GET `/orcid/authenticated` | `true` / `false` | `{"enabled":bool,"signedIn":bool,"orcid"?:string,"name"?:string}`: `orcid` and `name` only when signed in, only to that session | Changed (design) | +| 6 | POST `/orcid/claim/all` | Body: person id (text). Checks session, person, iD match; sends authored, reviewed and both, ≤100 per call, ORCID API v2.1; records the put-codes; `ClaimingSummary` | Same body, same answer; ORCID API v3.0; statuses per below | Same | +| 7 | POST `/orcid/claim/pa` | Pathways authored; as 6 | As 6 | Same | +| 8 | POST `/orcid/claim/pr` | Pathways reviewed; as 6 | As 6 | Same | +| 9 | POST `/orcid/claim/ra` | Reactions authored; as 6 | As 6 | Same | +| 10 | POST `/orcid/claim/rr` | Reactions reviewed; as 6 | As 6 | Same | +| 11 | GET `/orcid/{orcid}/works` | Checks session and that `{orcid}` is a Person whose iD is the session's; passes ORCID's v2.1 works list through (`Works`) | Same checks; answers the works **Reactome added** to the record, narrowed: `[{putCode, stId, title, type, url, createdDate, lastModifiedDate}]` (R7) | Changed (design) | +| 12 | GET `/orcid/let-us-know-your-orcid` | A page: the contact form pre-filled (subject, message with the iD), with the captcha key. Reverted port: JSON `{title, subject, message, tokenSession, captchaSiteKey}` | JSON `{title, subject, message}`; optional `?person=` adds the Person page's address to the message; never the token (the reverted port returned it) and no captcha key (the site has its own) | Changed (security) | + +Twelve rows for the old module's eleven endpoints: the callback is served at two addresses (FR-002). + +## Each endpoint + +### 1. `GET /orcid/login` + +- **Inputs**: `return` (optional): a path on this site. Anything not starting with exactly one `/`, or containing `\`, a scheme or a host, is replaced by `/`. +- **Does**: creates a pending sign-in (R3) under a new session cookie, or the existing one; `state` = 32 random bytes, base64url; PKCE verifier and S256 challenge if R4 holds. +- **Answers**: 302, `Location: {ORCID_AUTH_BASE}/oauth/authorize?client_id=…&response_type=code&scope=%2Factivities%2Fupdate&redirect_uri=…&state=…[&code_challenge=…&code_challenge_method=S256]`; `Set-Cookie` per FR-009. +- **Errors**: disabled: 404 envelope, `orcid.disabled`. Too many pending sign-ins for one cookie (more than 5): the oldest is dropped. + +### 2. `GET /orcid/callback` and `GET /content/orcid/callback` + +- **Inputs**: `code`, `state`, or `error`, `error_description`, `state` (ORCID's). +- **Does**: finds the pending sign-in by the cookie and `state` (constant-time compare; single use; ten minutes). With a code, POSTs `{ORCID_AUTH_BASE}/oauth/token` (form: `client_id`, `client_secret`, `grant_type=authorization_code`, `code`, `redirect_uri`, and `code_verifier` if R4), 30-second limit; on 200 with `access_token`, `orcid`, `scope` containing `/activities/update`: deletes the pending sign-in, creates a session under a **new** identifier, sets its cookie. +- **Answers**: always 302 to the site, `Referrer-Policy: no-referrer`: + - `/orcid-callback?outcome=signed-in&return=` + - `/orcid-callback?outcome=declined&return=` (`error=access_denied`) + - `/orcid-callback?outcome=failed&reason=&return=`, `reason` one of `state` (missing, unknown, used or expired), `exchange` (ORCID refused or did not answer), `scope` (granted less than asked). + - Never ORCID's `error_description` (it is ORCID's text, shown by ORCID already) and never the code. +- **Errors**: disabled: 404 envelope. + +### 3. `GET /orcid/token` + +Not served. 404, as any route the service does not have. + +### 4. `POST /orcid/signout` + +- **Inputs**: the session cookie; `Origin` must be the site's (FR-010). +- **Does**: deletes the session; clears the cookie (`Max-Age=0`); revokes the token at ORCID (FR-016), best effort, not waited on. +- **Answers**: 200, `text/plain`, `success` (as before), also when there was no session. +- **Errors**: wrong or missing `Origin`: 403 `orcid.origin`. GET: 405. + +### 5. `GET /orcid/authenticated` + +- **Answers**: 200, JSON (`OrcidStatus`): `{"enabled":false,"signedIn":false}` when disabled; `{"enabled":true,"signedIn":false}`; `{"enabled":true,"signedIn":true,"orcid":"0000-0002-1825-0097","name":"Placeholder Researcher"}`. +- Touches the session's last use. Never answers an error but 500. + +### 6–10. `POST /orcid/claim/{all|pa|pr|ra|rr}` + +- **Inputs**: body, `text/plain` (or any type, read as text, as Spring's `@RequestBody String` did), at most 64 bytes: a Person's dbId or ORCID iD, trimmed. `Origin` must be the site's. +- **Does**, in order: session (401) → origin (403) → claim already running for the session (409) → Person found by the same rule as `/data/person/{id}` (404) → Person has an ORCID iD (403 `orcid.person-without-orcid`) → equals the session's, ignoring case (403 `orcid.person-mismatch`) → reads the lists (`all`: the four; `pa`: authored pathways; `pr`: reviewed pathways; `ra`: authored reactions; `rr`: reviewed reactions) → for `all`, the events in both an authored and a reviewed list (by stable id) move to "both", per kind → builds works ([orcid-works.md](orcid-works.md)) → POSTs `{ORCID_API_BASE}/v3.0/{session iD}/works` with `Authorization: Bearer …`, at most 100 per request, in sequence → records the added works (FR-023). +- **Answers**: 200 `ClaimingSummary`: + + ```json + { "total": 12, "totalExecuted": 12, "totalIncluded": 9, "totalConflict": 3, "totalErrors": 0 } + ``` + + `total`: works to send; `totalExecuted`: works sent; `totalIncluded`: bulk items ORCID answered with a work; `totalConflict`: items ORCID answered with error 409 (already in the record); `totalErrors`: other per-item errors. As before. + +- **Errors**: 401 `orcid.signed-out` (no session, or ORCID answered 401: the session is then ended); 403 `orcid.origin`, `orcid.person-without-orcid`, `orcid.person-mismatch`; 404 `orcid.person-not-found`; 409 `orcid.claim-running`; 413 for a body over 64 bytes; 502 `orcid.unavailable` when a batch failed as a whole or timed out, with `user-message` stating how many works were added before it ("ORCID did not accept the request. 200 of 640 works were added; claiming again will add the rest without duplicating them."); 504 `orcid.too-long` past the 5-minute budget, worded the same way. +- **Old statuses**: not found, no iD and mismatch were 500 with `user-message` naming both iDs; ORCID's 401 was 401; any other ORCID error was 500 with ORCID's message. The new answers never name an iD other than the caller's own. + +### 11. `GET /orcid/{orcid}/works` + +- **Inputs**: `{orcid}`: a Person's ORCID iD (or dbId, as before: the old lookup took either). +- **Does**: the checks of 6–10 but the origin check (a GET); GETs `{ORCID_API_BASE}/v3.0/{session iD}/works`; keeps the summaries whose source is Reactome's client id. +- **Answers**: 200, JSON array (`OrcidWork[]`), sorted by stable id. +- **Errors**: as 6–10, without 409 and 413. + +### 12. `GET /orcid/let-us-know-your-orcid` + +- **Inputs**: `person` (optional): a Person's dbId or ORCID iD; ignored unless it names a Person. +- **Answers**: 200 JSON (`OrcidContactText`): `title` "Let us know your orcid", `subject` "[ORCID] Please add my orcid into Reactome", `message` the old text with the session's iD, followed, when `person` names one, by a line `Person page: {SITE_ORIGIN}/content/detail/person/{dbId}`. +- **Errors**: 401 `orcid.signed-out`. + +## Routing + +- nginx (`deploy/nginx/common/routes.conf`, deployed environments): one regex location for `^/ContentService/orcid/` and one exact location for `/content/orcid/callback` (and its trailing slash), both to the content service, with their own `limit_req` zone (`orcid_rate`, R9), `access_log off` on the callback locations, and a read timeout of 330 seconds on the claim locations. +- The dev proxy (`proxy.conf.js`) carries the same two entries; `deploy/nginx/routes.spec.ts` checks they agree. +- `/orcid-callback` is a site route (Angular), served as any page. diff --git a/specs/031-orcid-claim/contracts/orcid-works.md b/specs/031-orcid-claim/contracts/orcid-works.md new file mode 100644 index 00000000..1dd7d03c --- /dev/null +++ b/specs/031-orcid-claim/contracts/orcid-works.md @@ -0,0 +1,71 @@ +# Contract: the works sent to ORCID, and the calls made to it + +What the content service sends to ORCID. The stub ORCID (T006) accepts exactly this and refuses anything else, so a test that passes against the stub has sent what this page says. + +## Addresses + +| Call | Address | From settings | +| ---------------- | ------------------------------------------ | ----------------- | +| Authorise (page) | `{ORCID_AUTH_BASE}/oauth/authorize` | `ORCID_AUTH_BASE` | +| Token | `{ORCID_AUTH_BASE}/oauth/token` | `ORCID_AUTH_BASE` | +| Revoke | `{ORCID_AUTH_BASE}/oauth/revoke` (R5) | `ORCID_AUTH_BASE` | +| Works (bulk add) | POST `{ORCID_API_BASE}/v3.0/{orcid}/works` | `ORCID_API_BASE` | +| Works (list) | GET `{ORCID_API_BASE}/v3.0/{orcid}/works` | `ORCID_API_BASE` | + +ORCID's public documentation gives the sandbox as `https://sandbox.orcid.org` (authorise, token) and `https://api.sandbox.orcid.org` (Member API), and production as `https://orcid.org` and `https://api.orcid.org`. The production pair is refused without the production switch (FR-020). Every call is HTTPS with the system's certificate authorities, verified by name (the old client accepted any certificate), except to the stub on the loopback interface. + +Headers on API calls: `Authorization: Bearer `, `Accept: application/json`, and for the POST `Content-Type: application/vnd.orcid+json`. Each call has a 30-second limit. + +## One work + +Built from one event of the person lists (`SimpleEvent`, `projects/contract/person.ts`), as the old `OrcidHelper.createWork` built it, in ORCID's v3.0 names: + +```json +{ + "title": { "title": { "value": "" } }, + "short-description": "Pathway", + "type": "data-set", + "publication-date": { + "year": { "value": "2019" }, + "month": { "value": "06" }, + "day": { "value": "06" } + }, + "url": { "value": "{WORK_SITE_ORIGIN}/content/detail/R-HSA-0000000" }, + "external-ids": { + "external-id": [ + { + "external-id-type": "other-id", + "external-id-value": "R-HSA-0000000", + "external-id-url": { "value": "{WORK_SITE_ORIGIN}/PathwayBrowser/#/R-HSA-0000000" }, + "external-id-relationship": "self" + }, + { + "external-id-type": "doi", + "external-id-value": "10.3180/R-HSA-0000000.1", + "external-id-url": { "value": "https://doi.org/10.3180/R-HSA-0000000.1" }, + "external-id-relationship": "self" + } + ] + }, + "contributors": { + "contributor": [ + { + "contributor-attributes": { "contributor-sequence": "first", "contributor-role": "author" } + } + ] + } +} +``` + +- `short-description`: `Pathway` when the event's labels include `Pathway`, else `Reaction`. +- `publication-date`: from the event's `dateTime` (the edit's date, as before); left out when it is empty. +- The DOI identifier: pathways only, when `doi` is not blank, as before. Its address is `https://doi.org/…` (old: `http://dx.doi.org/…`, the same resolver). +- `WORK_SITE_ORIGIN` is a setting: Reactome's public site, so a work's links point at the public site even when it is claimed from the test site. The addresses keep the old paths, which the new site still answers. +- Contributors, by role, as before: **author** → one, `first`, `author`; **reviewer** → one, `additional`, `assignee`; **both** → the two. +- The `other-id` value is the stable id, as before: ORCID matches a work already in the record by its identifiers, so a work claimed by the old module and claimed again is a conflict (409), not a duplicate. This is why the type, value and relationship must not change. + +## The bulk add + +Body `{"bulk":[{"work":…},…]}`, at most 100. ORCID answers 200 with `{"bulk":[…]}`, one item per work in order, each either `{"work":{…,"put-code":…,"created-date":{"value":…},"last-modified-date":{"value":…}}}` or `{"error":{"response-code":409,…}}`. A 401 ends the session (FR-008); any other status, or no answer within 30 seconds, ends the claim (502). + +The v2.1 to v3.0 change (R6) alters names (`type` `data-set`, lower-case roles and sequences, the `vnd.orcid+json` media type), not what is sent. diff --git a/specs/031-orcid-claim/data-model.md b/specs/031-orcid-claim/data-model.md new file mode 100644 index 00000000..acefbbfa --- /dev/null +++ b/specs/031-orcid-claim/data-model.md @@ -0,0 +1,138 @@ +# Data model: ORCID "Claim your work" + +Two kinds of thing: what the content service holds in memory, and what crosses a boundary (to the site, to ORCID, to the report webapp). The answer types are in `projects/contract/orcid.ts` (spec 016: types only, written through by the service, read by the site). + +## Held in memory (`tools/content-node/sessions.ts`) + +Never answered, logged or written anywhere. + +### PendingSignIn + +| Field | Type | Notes | +| ----------- | ------ | ------------------------------------------------------ | +| `state` | string | 32 random bytes, base64url; the key it is found by | +| `verifier` | string | PKCE code verifier, 32 random bytes, base64url (if R4) | +| `returnTo` | string | A path on this site, already checked (FR-011) | +| `startedAt` | number | Milliseconds; gone after 10 minutes | + +At most five per session cookie; a sixth drops the oldest. Deleted on first use. + +### Session + +| Field | Type | Notes | +| ------------ | ------- | -------------------------------------------------------------------------- | +| `id` | string | 32 random bytes, base64url; the cookie's value; replaced at sign-in | +| `orcid` | string | From ORCID's token answer, `NNNN-NNNN-NNNN-NNNX` | +| `name` | string | From ORCID's token answer; may be empty (the researcher's choice at ORCID) | +| `token` | string | The access token | +| `scope` | string | Must include `/activities/update` | +| `expiresAt` | number | From ORCID's `expires_in`; a session past it ends | +| `signedInAt` | number | Absolute limit: 8 hours | +| `lastSeenAt` | number | Idle limit: 30 minutes | +| `claiming` | boolean | One claim at a time (FR-014) | + +ORCID's `refresh_token` is not kept. **States**: none → pending (login) → signed in (callback) → ended (sign-out, limit, ORCID 401, restart). A pending sign-in that fails leaves no session. + +## Answers (`projects/contract/orcid.ts`) + +```ts +/** GET /orcid/authenticated */ +export interface OrcidStatus { + enabled: boolean; + signedIn: boolean; + /** Only when signed in. */ + orcid?: string; + /** Only when signed in; ORCID's name for the account. */ + name?: string; +} + +/** POST /orcid/claim/{all|pa|pr|ra|rr}: the old module's ClaimingSummary, unchanged. */ +export interface ClaimingSummary { + total: number; + totalExecuted: number; + totalIncluded: number; + totalConflict: number; + totalErrors: number; +} + +/** GET /orcid/{orcid}/works: one work Reactome added to the record. */ +export interface OrcidWork { + putCode: number; + stId: string; + title: string; + /** ORCID's work type, `data-set` for every work Reactome adds. */ + type: string; + url?: string; + /** ISO 8601, ORCID's. */ + createdDate: string; + lastModifiedDate: string; +} + +/** GET /orcid/let-us-know-your-orcid */ +export interface OrcidContactText { + title: string; + subject: string; + message: string; +} + +/** Every error the family answers: the old module's ResponseError keys. */ +export interface OrcidError { + 'response-code': string; + 'developer-message': null; + 'user-message': string; + 'error-code': OrcidErrorCode; + 'more-info': null; +} + +export type OrcidErrorCode = + | 'orcid.disabled' + | 'orcid.signed-out' + | 'orcid.origin' + | 'orcid.person-not-found' + | 'orcid.person-without-orcid' + | 'orcid.person-mismatch' + | 'orcid.claim-running' + | 'orcid.too-large' + | 'orcid.unavailable' + | 'orcid.too-long'; +``` + +Sign-out answers `success` as text; the callback and login answer redirects. Neither has a JSON type. + +## Sent to ORCID + +The work and bulk bodies are in [contracts/orcid-works.md](contracts/orcid-works.md); their types live beside the client (`tools/content-node/orcid-client.ts`), not in the contract, because the site never reads them. + +## Read from the graph + +The Person (by dbId or ORCID iD, the rule `/data/person/{id}` uses: `personWhere` in `person-endpoints.ts`) and its four lists as `SimpleEvent` (`projects/contract/person.ts`): `stId`, `displayName`, `dateTime`, `doi`, `labels`. Nothing else. + +## Claim record (sent to the report webapp, if FR-023 decides so) + +One per work ORCID added, in the old module's `OrcidClaimRecord` shape, which the report webapp's claim-register call reads: + +| Field | Type | From | +| -------------- | ------ | -------------------------------------- | +| `stId` | string | The work's `other-id` identifier | +| `orcid` | string | The session's iD | +| `putCode` | number | ORCID's answer | +| `created` | string | ORCID's `created-date`, or empty | +| `lastModified` | string | ORCID's `last-modified-date`, or empty | + +No token, no name. The report webapp keys these by stable id and iD. + +## Settings (environment; values only in the host's private settings) + +| Name | Meaning | +| --------------------- | --------------------------------------------------------------------- | +| `ORCID_CLIENT_ID` | The ORCID client's id (sandbox until production switches) | +| `ORCID_CLIENT_SECRET` | Its secret | +| `ORCID_AUTH_BASE` | ORCID's authorise and token host | +| `ORCID_API_BASE` | ORCID's Member API host | +| `ORCID_REDIRECT_URI` | One of the registered redirect URIs | +| `SITE_ORIGIN` | This site's origin: the `Origin` POSTs must carry; where redirects go | +| `WORK_SITE_ORIGIN` | The public site's origin, written into works | +| `ORCID_PRODUCTION` | `1` to allow ORCID's production hosts; set by no one in this spec | +| `ORCID_STUB` | `1` to allow a loopback ORCID; tests only | +| `ORCID_TEST_PERSON` | Sandbox or stub only: `:` (FR-022, if decided so) | +| `REPORT_URL` etc. | Already the service's, for the search report (`report.ts`) | diff --git a/specs/031-orcid-claim/plan.md b/specs/031-orcid-claim/plan.md new file mode 100644 index 00000000..59ed3fc3 --- /dev/null +++ b/specs/031-orcid-claim/plan.md @@ -0,0 +1,115 @@ +# Implementation Plan: ORCID "Claim your work" on the node content service + +**Branch**: `spec/orcid-claim` | **Date**: 2026-11-17 | **Spec**: [spec.md](spec.md) + +**Input**: Feature specification from `specs/031-orcid-claim/spec.md` + +## Summary + +Port the old website's ORCID module (sign in with ORCID, claim one's authored and reviewed pathways and reactions as ORCID works, "let us know your ORCID") to the node content service as a family of its own, and give the new site's Person page its controls. The claims keep the old paths, body and answer; the sign-in is rebuilt: `state` (and PKCE if ORCID takes it), the code exchanged on the server in the callback, the token held only in the service's memory behind an opaque cookie, same-origin POSTs, sign-out by POST with revocation, the feature on exactly when its settings are complete, and ORCID's production servers refused without an explicit switch. Built and tested against a stub ORCID; then against ORCID's sandbox on the test site, once the maintainer has the sandbox client. Production is out of scope. + +## Technical Context + +**Language/Version**: TypeScript on Node 24 (the service runs `.ts` with type stripping, no build: spec 013); Angular for the site. + +**Primary Dependencies**: Express 5 (the service), Node's `fetch` and `crypto` (ORCID calls, random identifiers, S256). No new package. + +**Storage**: none of its own. Sessions in memory (R3). Claim records to the host's report webapp, if FR-023 decides so (R10). + +**Testing**: vitest for the service (stub ORCID on loopback, graph reads replaced as the person specs do); Playwright for the site, with `/ContentService/orcid/**` answered by the test; one whole-flow test of the service and the stub (T026); the sandbox by hand on the test site (quickstart). + +**Target Platform**: the content service's container on the host, behind nginx; the site. + +**Project Type**: web service family plus site feature, in one repository. + +**Performance Goals**: a claim of 3,300 works (34 batches) in under 5 minutes; `authenticated` as cheap as a map lookup. + +**Constraints**: no token, code, secret or iD in a log, answer or file (FR-007, FR-024); no request to ORCID from any test (FR-021); no Java; a family imports only shared modules (spec 014); answer types in the contract (spec 016); ratchets do not rise; the repository is public, so redirect URIs and hosts are written with placeholders. + +**Scale/Scope**: twelve routes (eleven old endpoints, one served at two addresses, one retired), three shared modules, one stub, the Person page's controls, one site route, one form. + +## Constitution Check + +_GATE: Must pass before Phase 0 research. Re-check after Phase 1 design._ + +| Principle | How this plan meets it | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| I. Verify the instrument | The stub validates every request it receives against [contracts/orcid-works.md](contracts/orcid-works.md) and refuses the rest, so "the stub accepted it" means "it was well formed". C17 proves no test can reach ORCID: a test pointed at the sandbox fails before any request. C4 and C18 scan for the stub's actual token and code strings, not for the word "token". | +| II. Measure in the thing | The whole flow runs through the real server against the stub (T026), and through the real site on the test site against the sandbox (T027) before the feature is called done. Site controls are asserted by their effect (the redirect's URL, the request sent), not their presence. | +| III. Prove a test fails | Every check has its breakage named in [contracts/checks.md](contracts/checks.md); each task records seeing it red. | +| IV. Stable identifiers | Works carry the stable id as their identifier and in their links; the "Let us know" message names the Person page by its address; the callback's `return` keeps the Person page's address as the reader had it. | +| V. Comments carry the failure | The comments the port needs are the old module's failures: no `state`, the GET sign-out, the token in the browser, the machine-name gate, the trust-any-certificate client. Each goes beside the code that replaces it, without exploitable detail. | +| Quality gates | Unchanged; preflight runs them. New code under `tools/` is TypeScript; the stub joins `tools/load.spec.ts`'s `SERVICES` and is importable without side effects. | +| Curator documents | `RELEASE-TESTING.md` and `CURATOR-REPORT.md` get rows for the claim flow (T028). | + +No violation. Re-checked after Phase 1: still none; one complexity is tracked below. + +## Project Structure + +### Documentation (this feature) + +```text +specs/031-orcid-claim/ +├── spec.md +├── plan.md # this file +├── research.md # R1–R13 +├── data-model.md +├── quickstart.md +├── contracts/ +│ ├── endpoints.md # the twelve routes, old against new +│ ├── orcid-works.md # what is sent to ORCID +│ └── checks.md # C1–C27, each with its breakage +├── checklists/ +│ └── requirements.md +└── tasks.md +``` + +### Source Code (repository root) + +```text +projects/contract/ +├── orcid.ts # OrcidStatus, ClaimingSummary, OrcidWork, OrcidContactText, OrcidError +├── routes.ts # + the ORCID JSON routes +└── openapi.json # regenerated + +tools/content-node/ +├── orcid-endpoints.ts # the family: login, callback ×2, signout, authenticated, claim ×5, works, let-us-know +├── orcid-client.ts # shared: token exchange, revoke, bulk add, list; host pinning; timeouts +├── orcid-works.ts # shared leaf: SimpleEvent → work, the batching, the summary +├── sessions.ts # shared: the in-memory store, cookie, limits +├── person-lists.ts # shared: the Person lookup and four lists, moved from person-endpoints.ts +├── settings.ts # + the ORCID settings and the enabled rule +├── report.ts # + claim records (if FR-023 decides so) +├── registry.ts # + orcidEndpoints +├── fixtures/route-order.json # + the new routes +└── orcid*.spec.ts # the checks + +tools/orcid-stub/ +└── stub.ts # startStubOrcid(): authorise page, token, revoke, works; loopback only + +deploy/nginx/ +├── common/routes.conf # + /ContentService/orcid/ and /content/orcid/callback +├── dev.conf, release.conf, production.conf # + limit_req_zone orcid_rate +└── routes.spec.ts # + the zone check +proxy.conf.js # + the two routes + +projects/website-angular/src/app/ +├── orcid/ # OrcidService (status, sign-in URL, claim, sign-out, contact text) +├── orcid/orcid-callback.component.* # the /orcid-callback route +├── orcid/orcid-contact.component.* # "Let us know your ORCID" form +├── content/detail/person-detail/ # the controls +└── app.routes.ts # + orcid-callback +e2e/orcid.spec.ts # the site's checks +projects/website-angular/content/about/privacy-notice.mdx, documentation/userguide/claim-your-work.mdx +documentation/declared-differences.md +``` + +**Structure Decision**: one family and three new shared modules in the content service, layered as spec 014 requires: `orcid-works.ts` and `sessions.ts` are leaves; `orcid-client.ts` imports only `settings.ts`; `person-lists.ts` imports what `person-endpoints.ts` imports for its lists today; the family imports these and nothing of another family. The stub is a tool directory of its own because it is a server that both the service's specs and a person running the quickstart start. + +## Complexity Tracking + +| Complexity | Why needed | Simpler alternative rejected because | +| ----------------------------------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| Server-side state in a so-far stateless service | The token must not reach the browser (FR-007); the old module kept it in a server session too | A token in a cookie, encrypted or not, sits in the browser and cannot be withdrawn by deleting it on our side | +| The store assumes one process | The service runs as one process per deployment | A shared store (database, cache) would be a store of long-lived credentials; if the service ever scales out, that decision comes first | +| A stub ORCID | No sandbox credentials yet; tests must never reach ORCID; the stub validates what is sent | Recording ORCID's answers would need the sandbox first, and would replay answers without checking requests | diff --git a/specs/031-orcid-claim/quickstart.md b/specs/031-orcid-claim/quickstart.md new file mode 100644 index 00000000..0c8caf66 --- /dev/null +++ b/specs/031-orcid-claim/quickstart.md @@ -0,0 +1,51 @@ +# Quickstart: trying "Claim your work" + +Three ways, from no credentials to the sandbox. None of them touches ORCID's production servers; the service refuses them without `ORCID_PRODUCTION=1`, which nothing here sets. + +## 1. The checks (no credentials, no network) + +```bash +npx vitest run tools/content-node/orcid tools/orcid-stub +npx playwright test --project=code e2e/orcid.spec.ts +``` + +The service's specs start the stub ORCID on a loopback port of their own; the site's spec answers `/ContentService/orcid/**` itself. A request to any other ORCID address fails the run (C17). + +## 2. The whole flow on a development machine, against the stub + +```bash +# the stub, on loopback; it prints its base address and its placeholder accounts +node tools/orcid-stub/stub.ts --port 4460 + +# the content service, pointed at it (placeholder values; nothing secret) +ORCID_STUB=1 \ +ORCID_CLIENT_ID=APP-STUB000000000000 ORCID_CLIENT_SECRET=stub-secret \ +ORCID_AUTH_BASE=http://127.0.0.1:4460 ORCID_API_BASE=http://127.0.0.1:4460 \ +ORCID_REDIRECT_URI=http://localhost:4200/ContentService/orcid/callback \ +SITE_ORIGIN=http://localhost:4200 WORK_SITE_ORIGIN=https:// \ +ORCID_TEST_PERSON=: \ +node tools/content-node/server.ts + +# the site, through the dev proxy (which sends /ContentService/orcid/ to the service) +npm start +``` + +Open a Person page, press "Sign in with ORCID". The stub's authorise page offers "Approve" and "Decline" for its placeholder accounts. Approve, land on `/orcid-callback`, return to the Person page, claim. The stub prints its tallies (works received, conflicts, batches) for comparison with the summary. + +## 3. The test site, against ORCID's sandbox + +Prerequisites (the maintainer; T001): + +1. The sandbox client, registered through ORCID's "Register a client application: Sandbox Member API" form, with only these redirect URIs: + - `https:///content/orcid/callback` + - `https:///ContentService/orcid/callback` + - `http://localhost:/content/orcid/callback` + - `http://localhost:/ContentService/orcid/callback` +2. Its id and secret, in the test site's private settings, beside `ORCID_AUTH_BASE=https://sandbox.orcid.org`, `ORCID_API_BASE=https://api.sandbox.orcid.org`, `ORCID_REDIRECT_URI` (one of the two test-site URIs), `SITE_ORIGIN=https://`, `WORK_SITE_ORIGIN`, and the `ORCID_TEST_PERSON` mapping if FR-022 is decided so. Nothing in the repository. +3. A sandbox ORCID account (ORCID's sandbox sends no mail to real addresses; use an address you control on a domain ORCID's sandbox accepts). + +Then: redeploy the content service; open the mapped Person's page on the test site; sign in with the sandbox account; claim all; check the works in the sandbox record; claim again (all conflicts, no duplicates); sign out; check `authenticated` says signed out and (if FR-016 is decided so) the grant is gone from the sandbox account's trusted organisations. + +## What to look for in the logs + +Counts and error codes only. If a token, code, secret, iD or name ever appears in the service's log, stop and file it: it is a failure of FR-024, whatever else works. diff --git a/specs/031-orcid-claim/research.md b/specs/031-orcid-claim/research.md new file mode 100644 index 00000000..b8a9e579 --- /dev/null +++ b/specs/031-orcid-claim/research.md @@ -0,0 +1,104 @@ +# Research: ORCID "Claim your work" on the node content service + +Decisions taken in writing this spec, each with what was considered. Sources: data-content's `org.reactome.server.orcid` package and its pages (the Person page's claim buttons, the callback page, the error handler); the reverted May 2026 ContentService port and its revert; the class and field names of the host's report webapp (no data read); ORCID's public documentation as known when writing, to be checked where marked **verify** (T003). No request was made to ORCID or to any Reactome service. + +## R1. Home: node, one family + +**Decision**: a family module `tools/content-node/orcid-endpoints.ts`, with shared modules beneath it: `orcid-client.ts` (every call to ORCID), `sessions.ts` (the session store and its cookie), and the Person lists' query moved out of `person-endpoints.ts` into a shared module so that two families can read it (a move, proved by `scripts/check-move.mjs`). + +**Why**: spec 010's rule (logic Reactome writes for the website, no Java library at its core) and the maintainer's decision of 16 Nov 2026. Spec 014's layout: a family imports only shared modules and leaves; `boundaries.spec.ts` holds it. + +**Rejected**: the Java ContentService (decided against); a separate service (a second process, image and nginx upstream for twelve routes, and a second reader of the Person lists). + +## R2. Endpoint shapes: keep the old where safe, declare the rest + +Nothing serves these endpoints, so there is no live answer to be byte-identical to. The claims (paths, method, body, `ClaimingSummary`) and sign-out's body are kept, because the site's code and the user guide describe them and nothing about them is unsafe. Changed: the callback (finishes the exchange itself), `token` (retired), sign-out (POST), `authenticated` (says whether the feature is on, and who is signed in), `works` (narrowed), `let-us-know-your-orcid` (no token, no captcha key), error statuses. Each is a row in the register of declared differences, added with this spec. + +## R3. Sessions: server-side, in memory, opaque cookie + +**Decision**: a `Map` in the content service's memory from a 256-bit random identifier to the session; cookie `reactome_orcid` (`HttpOnly`, `Secure` except on a loopback development address, `SameSite=Lax`, `Path=/`), holding only the identifier. Pending sign-ins live in the same store for ten minutes. Idle limit 30 minutes, absolute 8 hours. At most 10,000 sessions; past that, the least recently used goes (measured need is a handful at a time: the old feature's claims were counted in a daily digest). + +**Why**: the token is a bearer credential for writing to a researcher's ORCID record, valid for years. Kept on the server, a script injected into the site cannot read it; kept in memory, it never reaches a disk, a backup or another service. A restart signs everyone out, which costs a researcher one more sign-in. + +**`Path=/`**: the callback is served at `/ContentService/orcid/callback` and `/content/orcid/callback` (FR-002); a cookie scoped to either prefix would not reach the other. The cookie's name is the family's own, and nothing else on the site reads it. + +**`SameSite=Lax`, not `Strict`**: ORCID's redirect back to the callback is a cross-site top-level navigation; `Strict` would withhold the cookie there and fail every sign-in. + +**Rejected**: Express's session middleware (a dependency for one map, and its defaults would need overriding one by one); a signed or encrypted cookie holding the token (the token would then sit in the browser, encrypted or not, and could not be revoked by deleting it on our side); a database (a store of long-lived credentials is the thing to avoid). + +**One process**: the service runs as one process per deployment today. If that changes, sessions need a shared store first; the plan's Complexity Tracking names it. + +## R4. `state` and PKCE + +**`state`**: required. 32 random bytes, base64url, bound to the cookie's pending sign-in, compared in constant time, deleted on first use, ten minutes. The old module sent none, so a visitor could be signed in to an account of someone else's choosing (login CSRF), and could then claim works into it. + +**PKCE (S256)**: ORCID's OAuth server is an implementation of the standard authorisation-code flow; whether its Member API token endpoint accepts and checks `code_verifier` for a confidential client is to **verify** on the sandbox (T003). If it does, send it: it binds the code to this sign-in even if the code leaks. If ORCID ignores it, sending it is harmless but proves nothing, and the spec's protection rests on `state`, the client secret and the server-side exchange. The stub checks it either way, so the code is ready. + +**OpenID Connect `nonce`**: not used. Reactome requests `/activities/update`, not `openid`; the iD comes back in the token answer. + +## R5. Token lifetime and revocation + +ORCID's access tokens are long-lived (the old module's own comment shows an `expires_in` of about 20 years). Reactome uses a token only within the session that obtained it. + +**Revocation**: ORCID documents a revocation endpoint for member clients (`/oauth/revoke`, client credentials and the token; **verify** on the sandbox, T003). The recommendation in FR-016 is to call it, best effort, at sign-out and at expiry, so that no grant outlives the session. The alternative, keeping the grant, only makes sense if Reactome will later write to records unprompted (for instance to update claimed works when an event changes), which nothing does or plans; that is the open question. + +**Refresh tokens**: never used; discarded on receipt. + +## R6. ORCID Member API version + +The old module called v2.1. ORCID's current Member API is v3.0, and ORCID has been retiring v2.x (**verify** dates, T003). The port uses v3.0. The names change (`type` `data-set`, lower-case contributor roles and sequences, the `application/vnd.orcid+json` media type, put-codes and dates in the same places); what is sent does not ([contracts/orcid-works.md](contracts/orcid-works.md)). The bulk limit stays 100 works per request (**verify**). + +**Roles kept as they were**: a reviewer is written as contributor role `assignee`, sequence `additional`, as the old module wrote it. ORCID's role vocabulary has no "reviewer" for works; changing the mapping would make re-claimed works differ from those already in researchers' records. A change is a separate decision. + +## R7. `{orcid}/works` + +The old endpoint passed ORCID's whole works list through, which carries every work in the record, from every source, and nothing in the old site called it. The new answer keeps the same checks but narrows to the works Reactome's client added (`source-client-id` equals the client id), as `OrcidWork`: what the site needs to mark "already in your ORCID record". Whether `/activities/update` lets Reactome read its own works whatever their visibility is to **verify** (T003); ORCID's documentation says a source can read the items it added. + +## R8. Turning the feature on and off + +The old gate compared the server's machine name with a configured one, so a copy of the configuration on another machine was off, and on the production machine it was on whatever the credentials. The replacement: on exactly when all settings are present and valid (`ORCID_CLIENT_ID`, `ORCID_CLIENT_SECRET`, `ORCID_AUTH_BASE`, `ORCID_API_BASE`, `ORCID_REDIRECT_URI`, `SITE_ORIGIN`, `WORK_SITE_ORIGIN`), and off, with one start-up line naming the missing setting (never its value), otherwise. ORCID's production hosts are refused unless `ORCID_PRODUCTION=1` is also set, which nothing in this spec sets. The stub's loopback address is accepted only with `ORCID_STUB=1`, which only tests set. + +## R9. Rate limits + +**Our side**: an nginx zone `orcid_rate`, per client address: 30 requests a minute, burst 10. A sign-in is three requests (login, callback, authenticated); a claim one; a page view one (`authenticated`). Applied to `/ContentService/orcid/` and the old callback address. + +**ORCID's side**: ORCID publishes per-client limits for the Member API (of the order of tens of requests a second, with a burst; **verify**, T003). A claim's batches are sent in sequence, one at a time, so a single claim cannot approach them; FR-014's one-claim-per-session and nginx's zone bound the total. + +## R10. The record of claims, and what is not recorded + +The old module sent two things to the host's report webapp, fire-and-forget: each claim's added works (stable id, ORCID iD, put-code, created and last-modified dates), and a record of each sign-in. The report webapp keeps them (its classes `OrcidClaim`, keyed by stable id and iD; a sign-in class; `OrcidDigester`, a per-person count) and mails a daily and weekly claiming digest to the team (`OrcidReportScheduler`). + +**Recommendation** (FR-023, open question): send the claim records to the report webapp through the same call the old module used, as `report.ts` already sends search reports there (its address and credentials are settings the service already has); send **no** sign-in record: the reports do not need one, and the sign-in carries the access token, which leaves the service's memory for nowhere. The report webapp's digest keeps working on claims. Replacing the report webapp, or the store it keeps, is not this spec's. + +**Alternatives**: node keeps its own record (a second store of the same facts, and the digest would not see it); no record (the team loses its claiming reports). + +## R11. Sandbox accounts and the Person check + +A claim is allowed only when the session's iD equals the Person's recorded iD. ORCID's sandbox issues its own iDs; none equals a real contributor's. So on the test site, with the real graph, no sandbox account can claim anything unless something maps one to a Person (FR-022, open question). + +**Recommendation**: a test-only setting, `ORCID_TEST_PERSON=:`, honoured only when the stub or the sandbox is configured, and refused at start-up alongside production settings; it names a Person whose owner has agreed (for instance, a team member's own record), in the host's private settings, never in the repository. The works then go to a sandbox record, which ORCID's sandbox exists for. + +**Alternatives**: a synthetic Person in the test graph only (needs a change to the graph the test site serves, which is a release image); no claim on the test site (Story 2 would be proved against the stub only). + +## R12. The site + +- **Full-page redirect, not a popup**: the old page opened ORCID in a popup and reloaded the opener. Popups are blocked by default in many browsers, and the opener dance needs script on both pages. The new flow navigates away and back, carrying the Person page as `return`. +- **`/orcid-callback`** shows the outcome and navigates to `return` (checked again on the site side: a path on this site) after a short pause, or at once on a click. +- **Claim controls** on the Person page only, as before: "Claim all your works" in the header, the four narrower buttons beside their lists, each with a confirmation stating the count, the summary in a dialog with a link to the researcher's ORCID record. +- **"Let us know your ORCID"** opens a small form (name, e-mail, the pre-filled subject and message, the Turnstile widget) that posts to `POST /ContentService/contact`, the content service's help-desk endpoint (spec 006 D23), so the human check, limits and mail path are the ones already reviewed. +- **The user guide** (`documentation/userguide/claim-your-work.mdx`) describes the popup; T025 updates its words. Its screenshots wait for the curator's new ones. + +## R13. Privacy + +What the feature handles: researchers' ORCID iDs and names (from ORCID's token answer), their access tokens, and which Reactome events they claimed. + +| Data | Where | How long | Who can read it | +| ---------------------------- | --------------------------------------- | ---------------------------------------------- | ----------------------------------------- | +| Access token, iD, name | Content service memory (session) | ≤ 30 minutes idle, ≤ 8 hours, ends at sign-out | No one: never answered, logged or written | +| iD, name | The signed-in browser (`authenticated`) | The page's life | That browser | +| Claim records (no token) | Report webapp (if FR-023 decides so) | As the report webapp keeps them today | The team, via its reports, as today | +| Callback query (code, state) | Nowhere: nginx logs off for it | — | — | + +The privacy notice already covers contributors' names and iDs for credit attribution; T025 adds a paragraph on the sign-in, for the maintainer's approval (FR-027). + +**Tests and fixtures**: the stub's accounts are placeholder people (`Placeholder Researcher`) with iDs from ORCID's documentation examples (`0000-0002-1825-0097`, ORCID's fictitious example researcher) or issued by the stub from a reserved range it documents, never a contributor's. The fixture Persons are placeholders too, under the repository's fixture rule (placeholder all people and the free text that cites them). diff --git a/specs/031-orcid-claim/spec.md b/specs/031-orcid-claim/spec.md new file mode 100644 index 00000000..f4381b31 --- /dev/null +++ b/specs/031-orcid-claim/spec.md @@ -0,0 +1,210 @@ +# Feature Specification: ORCID "Claim your work" on the node content service + +**Feature Branch**: `spec/orcid-claim` + +**Created**: 2026-11-17 + +**Status**: Draft + +**Input**: Maintainer's decision, 16 Nov 2026: "Keep 'Claim your work': it is an important part of the curation process. Port it to the node content service, never to Java and never with a Java fallback. Reactome is an ORCID member organisation. All development and testing uses ORCID's Sandbox Member API, with its own client id and secret, registered with non-production redirect URIs only; production credentials come later. Until the sandbox key exists, build and test against a stub ORCID. Register both `/content/orcid/callback` and `/ContentService/orcid/callback` on the sandbox client, for the test site and localhost. Credentials live in the host's private settings and are read from the environment, never in the repository." + +## Background + +"Claim your work" lets a researcher who authored or reviewed Reactome pathways and reactions add them, as works, to their own ORCID record. They sign in with ORCID on their Person page, grant Reactome permission to add works, and press a button; Reactome writes one work per pathway or reaction, through ORCID's Member API, with the pathway's stable id (and its DOI, where it has one) as the work's identifiers. ORCID records these as contributions credited by Reactome, which matters to the volunteers who author and review Reactome's content. + +The feature was served by the old website's content pages (data-content's `org.reactome.server.orcid` package). It was ported verbatim to the Java ContentService in May 2026 and reverted three days later "until the team discusses it". Nothing serves it today: the new site's Person page (#99) has no claim buttons, and issue #114 has waited on a backend since August. Spec 006 lists it as its last task, T110. The discussion is settled: the feature stays, and its home is node, by spec 010's rule (it is logic Reactome writes for the website, with no Java library at its core). + +Because nothing serves these endpoints, there is no Java answer to compare against, so spec 006's rule that a ported endpoint is byte-identical to Java's cannot apply as it does elsewhere. This spec instead keeps each endpoint's path, method, inputs and success shape as the old module had them wherever that is safe, and declares every change, with its reason, in the [register of declared differences](../../documentation/declared-differences.md). + +The old module's security model does not survive a port as it stands. It sent no `state` parameter, so a sign-in could be forced on a visitor; it signed out on a GET; the reverted port returned the whole token record, access token included, to the browser; its outbound connections accepted any certificate; and it was switched on by comparing the server's machine name with a configured one. This spec replaces each of these. + +## User Scenarios & Testing _(mandatory)_ + +The users are Reactome's authors and reviewers (researchers, signed in with ORCID, on their own Person page), the help desk (who receive "let us know your ORCID" messages), and the maintainer (who holds the ORCID client credentials and decides when production switches). + +### User Story 1 - Sign in with ORCID from the Person page (Priority: P1) + +A researcher opens their Person page, presses "Sign in with ORCID", grants Reactome permission on ORCID's page, and lands back on the same Person page, signed in, with their ORCID iD shown as the signed-in account. They can sign out, and signing out ends the sign-in on Reactome's side. + +**Why this priority**: every other story needs a signed-in session; on its own it proves the OAuth round trip, the credentials and the redirect URIs. + +**Independent Test**: against the stub ORCID (and later the sandbox), follow the sign-in from a Person page and back; `GET /ContentService/orcid/authenticated` reports signed in with the stub account's iD; sign out; it reports signed out. + +**Acceptance Scenarios**: + +1. **Given** a visitor not signed in on a Person page, **When** they press "Sign in with ORCID", **Then** the browser goes to ORCID's authorise page with Reactome's client id, scope `/activities/update`, a registered redirect URI and a fresh `state`. +2. **Given** ORCID sends the browser back with a code and the matching `state`, **When** the callback is handled, **Then** the content service exchanges the code for a token itself, the browser never sees the token or the code again, and the visitor lands on `/orcid-callback`, which confirms the sign-in and returns them to the Person page they started from. +3. **Given** ORCID sends the browser back with `error=access_denied` (the researcher declined), **When** the callback is handled, **Then** the visitor sees "You did not grant Reactome access to your ORCID record; nothing was changed" and is not signed in. +4. **Given** a callback whose `state` is missing, unknown, already used or older than ten minutes, **When** it arrives, **Then** no code is exchanged, no session is created, and the visitor sees "The sign-in could not be completed; please try again". +5. **Given** a signed-in visitor, **When** they press "Sign out", **Then** the session is deleted on the server, its cookie cleared, and (subject to FR-016) the access token revoked at ORCID. + +--- + +### User Story 2 - Claim your works (Priority: P1) + +A signed-in researcher whose ORCID iD matches the Person page's ORCID presses "Claim all your works" (or one of the four narrower buttons: pathways authored, pathways reviewed, reactions authored, reactions reviewed), confirms the number of works to be added, and sees a summary: how many were sent, how many ORCID added, how many were already in their record, and how many failed. + +**Why this priority**: this is the feature. Story 1 alone adds nothing to anyone's record. + +**Independent Test**: against the stub ORCID, sign in as a stub account mapped to a fixture Person, claim all; the stub received one bulk request per 100 works, each work built as [contracts/orcid-works.md](contracts/orcid-works.md) says, and the summary's counts equal the stub's tallies. + +**Acceptance Scenarios**: + +1. **Given** a signed-in researcher on their own Person page, **When** they claim all, **Then** each pathway and reaction they authored or reviewed is sent once: as author, as reviewer, or as both when they did both, in batches of at most 100. +2. **Given** some of those works are already in their ORCID record from an earlier claim, **When** they claim again, **Then** ORCID reports those as conflicts, no duplicates are created, and the summary counts them as "already in your record". +3. **Given** a signed-in researcher on **another** person's page, **When** a claim is sent for that page (by the button being shown in error, or by a hand-made request), **Then** it is refused with 403 and nothing is sent to ORCID. +4. **Given** a Person page with no ORCID recorded in Reactome, **When** a claim is sent for it, **Then** it is refused with 403 and the page offers "Let us know your ORCID" instead (Story 3). +5. **Given** ORCID rejects the token partway through (revoked by the researcher on ORCID's site), **When** the next batch is sent, **Then** the claim stops, the session ends, and the researcher is told to sign in again; what was already added stays added and is reported. +6. **Given** a claim is running for a session, **When** a second claim is sent for the same session, **Then** it is refused with 409 until the first finishes. + +--- + +### User Story 3 - Let us know your ORCID (Priority: P2) + +A signed-in researcher whose Person page has no ORCID recorded (or a different one) is offered "Let us know your ORCID". It opens a short help-desk form, pre-filled with a subject and a message that carry their signed-in ORCID iD and the Person page they are on, protected by the site's human check, and sent through the content service's contact endpoint. + +**Why this priority**: it is how a contributor's ORCID iD reaches Reactome's records so that Story 2 can work for them at the next release; useful, but not needed for the researchers whose iD is already recorded. + +**Independent Test**: signed in as a stub account on a fixture Person with no ORCID, open the form; it carries the stub iD and the page's address; sending it reaches `POST /ContentService/contact` with those fields (the mail sender replaced, as the contact specs replace it). + +**Acceptance Scenarios**: + +1. **Given** a signed-in researcher on a Person page without an ORCID, **When** they open "Let us know your ORCID", **Then** the subject is "[ORCID] Please add my orcid into Reactome" and the message names their ORCID iD and the Person page's address. +2. **Given** a visitor who is not signed in, **When** the form's text is requested, **Then** the answer is 401 and the site offers "Sign in with ORCID" first. + +--- + +### User Story 4 - The test site uses ORCID's sandbox; nothing touches production ORCID (Priority: P2) + +The maintainer installs the sandbox client's id and secret in the test site's private settings. The test site then signs in against ORCID's sandbox and writes works to sandbox accounts only. No automated test, on any machine, ever calls ORCID's production servers, and a deployment cannot be pointed at production ORCID by accident. + +**Why this priority**: it is the gate between "built against a stub" and "known to work with ORCID", and the guarantee that testing never writes to a real researcher's record. + +**Independent Test**: on the test site, with sandbox settings, sign in as a sandbox account and claim; the works appear in that sandbox record. With the production authorise address configured and no explicit production switch, the feature reports itself disabled. + +**Acceptance Scenarios**: + +1. **Given** no ORCID settings, **When** the content service starts, **Then** the ORCID endpoints answer as disabled (FR-019) and the site shows no ORCID buttons. +2. **Given** settings that name ORCID's production servers but not the explicit production switch, **When** the content service starts, **Then** the feature is disabled and the start-up log says why (without any secret). +3. **Given** the test suites, **When** they run, **Then** every ORCID call goes to the stub, on the loopback interface; a call to any other ORCID address fails the test. + +--- + +### User Story 5 - Reactome keeps a record of what was claimed (Priority: P3) + +After each claim, the stable ids of the works ORCID added, with the ORCID iD and ORCID's put-codes and dates, are recorded where the team's claim reports read them, as they were before. No access token is recorded anywhere. + +**Why this priority**: the team's claim reports depend on it, but a claim succeeds for the researcher without it. + +**Independent Test**: with the record store replaced by a stub, a claim of three works that ORCID adds sends one record per added work, with the fields in [data-model.md](data-model.md), and nothing else; with the store down, the claim still answers its summary. + +**Acceptance Scenarios**: + +1. **Given** a claim where ORCID added 3 works and reported 2 conflicts, **When** it finishes, **Then** 3 claim records are sent, each with stable id, ORCID iD, put-code, created and last-modified dates. +2. **Given** the record store is unreachable, **When** a claim finishes, **Then** the researcher's answer is unaffected and the failure is logged by code, without the ORCID iD. + +--- + +### Edge Cases + +- **A person with thousands of works.** A curator with about 3,300 authored reactions means 34 bulk requests. The claim runs them in sequence, within ORCID's rate limit, and the site shows progress as "working" until the summary arrives (FR-012's time budget). +- **An event that is both authored and reviewed** by the same person is sent once, as both, never twice. +- **An event listed once per edit.** The node person lists already list an event once, at its latest edit (a difference spec 006 declares); the claim uses them as they are. +- **A pathway with a DOI** gets the DOI as a second identifier; a reaction never does, as before. +- **An event with no edit date** is sent without a publication date. +- **ORCID's answer to a batch is an error for the whole batch** (400, 500, timeout): the claim stops; earlier batches stand; the summary says how many were added and that the rest were not attempted. +- **The sign-in is older than its limit** (FR-008): the next request answers 401 and the site offers sign-in again. +- **The content service restarts**: every session is gone, and visitors sign in again (FR-007). +- **The return address in `login`** is anything but a path on this site (`//evil.example`, `https://…`, `javascript:`): it is replaced by the site's home page, never followed. +- **Two tabs**: a sign-in started in one tab and finished in another works, since `state` is checked against the session cookie, not the tab. +- **Cookies refused by the browser**: the callback cannot match `state` and fails with "sign-in could not be completed"; the site's message mentions cookies. +- **A sandbox ORCID iD on the test site** can never equal a real Person's recorded iD, so Story 2 cannot be shown on the test site without a test-only mapping (FR-022, and the open question there). + +## Requirements _(mandatory)_ + +### Functional Requirements + +#### The endpoints + +- **FR-001**: The node content service MUST serve the ORCID family under `/ContentService/orcid/`, as one family module, with each endpoint's behaviour as [contracts/endpoints.md](contracts/endpoints.md) gives it. Every route takes a trailing slash, as Spring's did. None is ever answered by Java, as a fallback or otherwise. +- **FR-002**: The callback MUST also be served at `/content/orcid/callback`, the old module's address, with identical behaviour, so that either redirect URI registered with ORCID works and production can switch without registering a new one. +- **FR-003**: `/orcid/token` MUST NOT be served (a 404, as any unknown route): the code is exchanged by the callback on the server, and never reaches the site. +- **FR-004**: The five claim endpoints MUST keep the old module's paths (`/orcid/claim/all|pa|pr|ra|rr`), method (POST), body (the Person's dbId or ORCID iD, as plain text) and success answer (`ClaimingSummary`'s five counts, same names, same meaning). +- **FR-005**: Each answer's JSON shape MUST be a type in `projects/contract/` (spec 016), written through it by the service and read through it by the site, with a row in `routes.ts` and the regenerated OpenAPI description. + +#### Sign-in and sessions + +- **FR-006**: Sign-in MUST use OAuth 2.0's authorisation-code flow with a confidential client, a single-use random `state` (at least 128 bits) bound to the visitor's session cookie and good for ten minutes, and PKCE (S256) if ORCID's Member API accepts it (research R4); the code is exchanged on the server, with the client secret, once. +- **FR-007**: The access token, and everything ORCID returns with it, MUST be kept only in the content service's memory, in a server-side session the browser knows only by an opaque random identifier. The browser never receives the token, the refresh token or the code. Nothing writes them to disk, a database, another service or a log. +- **FR-008**: A session MUST end after 30 minutes without a request, 8 hours after sign-in, at sign-out, when ORCID rejects its token, or when the service restarts. The session identifier MUST be replaced at sign-in (no fixation). +- **FR-009**: The session cookie MUST be `HttpOnly`, `Secure` (except on a loopback development address), `SameSite=Lax` (so it reaches the callback, a top-level navigation from ORCID), path `/` (the callback has two addresses under different prefixes, research R3), and carry no data but the identifier. +- **FR-010**: Every POST in the family MUST be refused (403) unless its `Origin` header is the site's own; sign-out MUST be a POST. +- **FR-011**: The `login` endpoint MUST accept a return path and send the visitor back to it after sign-in only if it is a path on this site (begins with a single `/`, no scheme, no host, no backslash); otherwise the site's home page. + +#### Claiming + +- **FR-012**: A claim MUST read the person's authored and reviewed pathways and reactions with the same queries as the Person page's four lists (`/data/person/{id}/…`), send an event both authored and reviewed once as both, build each work as [contracts/orcid-works.md](contracts/orcid-works.md) gives it, send at most 100 works per request to ORCID's Member API v3.0, in sequence, each with a 30-second limit, and answer within 5 minutes or stop and say how far it got. +- **FR-013**: A claim MUST be refused unless the session's ORCID iD equals the Person's recorded ORCID iD (case-insensitively, as before): 404 when there is no such Person, 403 when the Person has no ORCID iD or a different one. The ORCID iD a claim writes to is always the session's, never one from the request. +- **FR-014**: At most one claim MUST run per session at a time (409 for another). +- **FR-015**: Errors MUST be answered in the family's envelope (the old module's `ResponseError` keys) with a `user-message` fit to show and an `error-code` the site can branch on; never with ORCID's own developer text, a token, or a stack trace. + +#### Tokens at ORCID + +- **FR-016**: At sign-out and at session expiry, the service MUST [NEEDS CLARIFICATION: revoke the access token at ORCID, or leave Reactome's grant in place? Recommendation: revoke, best effort, with ORCID's revocation endpoint (research R5). Reactome never uses a token after the session, so a long-lived grant (ORCID's tokens last about 20 years) is risk with no use; a future feature that updates works would ask the researcher again.] + +#### Disabled, sandbox and production + +- **FR-017**: The ORCID client id, client secret, ORCID's authorise and API base addresses, the site's origin and the redirect URI MUST be read from the environment (the host's private settings); none is in the repository, a log, or an answer. +- **FR-018**: The feature MUST be enabled exactly when those settings are complete and valid. This replaces the old machine-name gate. +- **FR-019**: When disabled, `GET /orcid/authenticated` MUST answer `{"enabled":false,"signedIn":false}`, every other ORCID endpoint 404 in the family's envelope, and the site MUST show no ORCID control. +- **FR-020**: Settings naming ORCID's production servers MUST leave the feature disabled unless an explicit production switch is also set; this spec does not set it anywhere. +- **FR-021**: No automated test MUST send a request to any ORCID server; tests use a stub on the loopback interface, and a request elsewhere fails the test. +- **FR-022**: On the test site, a sandbox ORCID iD MUST be matched to a Person by [NEEDS CLARIFICATION: how? Recommendation: a test-only setting that maps one sandbox iD to one Person's dbId, honoured only when the sandbox or stub is configured (never with production settings), naming a Person whose owner has agreed to it; the alternatives are a synthetic Person in the test graph only, or no claim test on the test site.] + +#### The record of claims + +- **FR-023**: After each claim, the service MUST [NEEDS CLARIFICATION: send one record per work ORCID added (stable id, ORCID iD, put-code, created and last-modified dates) to the host's report webapp, which keeps owning the record and its reports — or keep its own, or none? Recommendation: the report webapp, through its existing claim-register call, fire-and-forget as `report.ts` already reports searches, sending claims only and never a token; the old module's separate sign-in record is not sent.] + +#### Privacy and logging + +- **FR-024**: The service MUST NOT log access tokens, refresh tokens, codes, `state`, session identifiers, cookies, names or ORCID iDs. Failures are logged by error code and counts. The web server's access log MUST NOT record the callback's query string. +- **FR-025**: Every answer in the family MUST carry `Cache-Control: no-store`; the callback's redirect MUST carry `Referrer-Policy: no-referrer`. +- **FR-026**: Tests, fixtures and recordings MUST use placeholder people and ORCID iDs from the stub or the sandbox only: no real person's name, iD, record or token in the repository, logs or test output. +- **FR-027**: The site's privacy notice MUST say what the ORCID sign-in keeps (the session in memory for at most 8 hours; the claim records, per FR-023) before the feature is offered on the test site, in wording the maintainer approves. + +#### Rate limits + +- **FR-028**: The web server MUST budget the family per client address (its own zone, as the contact form has), and the service MUST stay within ORCID's published request rate for its own calls. + +#### The site + +- **FR-029**: The Person page MUST show, when the feature is enabled: "Sign in with ORCID" to a visitor not signed in; when signed in as the page's person, "Claim all your works" and the four narrower claim buttons beside their lists, each with a confirmation that states how many works will be added; the signed-in iD and "Sign out"; and, when signed in on a page whose Person has no or another ORCID iD, "Let us know your ORCID". +- **FR-030**: The site MUST have an `/orcid-callback` route that shows the sign-in's outcome (success, declined, failed) in words, and returns to the Person page the sign-in started from. +- **FR-031**: The site MUST show each claim error's `user-message`, and on 401 offer sign-in again. + +### Key Entities + +- **Sign-in session**: what the service holds for one signed-in browser: the ORCID iD, the name ORCID returned, the access token and its scope and expiry, the sign-in time and last use. In memory only. +- **Pending sign-in**: a sign-in started and not finished: the `state`, the PKCE verifier, the return path, the start time. In memory only, ten minutes. +- **Work**: one pathway or reaction as an ORCID work: title, type, short description, publication date, the stable id and DOI as identifiers, Reactome addresses, and the contributor role. +- **Claiming summary**: the five counts a claim answers. +- **Claim record**: one work ORCID added, for the team's reports: stable id, ORCID iD, put-code, created and last-modified dates. + +## Success Criteria _(mandatory)_ + +### Measurable Outcomes + +- **SC-001**: On the test site with sandbox credentials, a sandbox account completes sign-in, a claim of all its mapped Person's works, and sign-out, and the works appear in the sandbox record, with no duplicates after a second claim. +- **SC-002**: Every row of [contracts/checks.md](contracts/checks.md) is a test that has been shown failing against a broken implementation before it passed (constitution III). +- **SC-003**: A search of the repository, the service's logs from the test run and the test output finds no access token, code, client secret or real ORCID iD. +- **SC-004**: With no ORCID settings, or with production addresses and no production switch, no ORCID control appears on any Person page and every ORCID endpoint but `authenticated` answers 404. +- **SC-005**: A claim of 3,300 works against the stub completes, in batches of at most 100, within the 5-minute budget. +- **SC-006**: Every difference from the old module is a row in the register of declared differences. + +## Assumptions + +- The sandbox client is registered by the maintainer with only non-production redirect URIs (`https:///content/orcid/callback`, `https:///ContentService/orcid/callback` and the same two under `http://localhost:`); its id and secret are installed in the test site's private settings by the maintainer. +- The content service runs as one process per deployment, so an in-memory session store is shared by every request. If it ever runs as several, sessions move to a shared store first (plan, Complexity Tracking). +- The site and the content service are served from the same origin (nginx routes `/ContentService/` on the site's host), so a cookie the service sets is sent with the site's requests. +- Scope `/activities/update` is what Reactome requests, as before; nothing else. +- Out of scope: production credentials, switching production on, updating or deleting works already claimed, and claiming from any page but the Person page. diff --git a/specs/031-orcid-claim/tasks.md b/specs/031-orcid-claim/tasks.md new file mode 100644 index 00000000..229925ba --- /dev/null +++ b/specs/031-orcid-claim/tasks.md @@ -0,0 +1,92 @@ +--- +description: 'Tasks for spec 031: ORCID "Claim your work" on the node content service' +--- + +# Tasks: ORCID "Claim your work" on the node content service + +**Input**: [plan.md](plan.md), [spec.md](spec.md), [research.md](research.md), [data-model.md](data-model.md), [contracts/](contracts/), [quickstart.md](quickstart.md) + +This spec replaces spec 006's T110, which now points here. + +**Every task**: + +- Is one pull request, with its own adversarial review, and ticks this file with its PR number in that same pull request. +- Shows each new check failing before it is trusted (constitution III); [contracts/checks.md](contracts/checks.md) names the breakage, and the tick records that it was seen red. +- Sends no request to ORCID (only the stub, on loopback), to the graph database or to Reactome services from a test. +- Puts no real person's name, ORCID iD, record or token in code, fixtures, logs, test output, commit messages or pull request descriptions; no host name, path or credential either (the repository is public). +- Never lets the lint, dead-code, loose-value or known-problems counts rise. +- Keeps the register of declared differences current: a row's status moves from "spec only" as its task lands. + +## Format: `[ID] [P?] [Story] Description` + +## Phase 1: Setup (the maintainer's part, and what ORCID's documentation says) + +- [ ] T001 [US4] The maintainer registers the sandbox client through ORCID's "Register a client application: Sandbox Member API" form, with only the four non-production redirect URIs in [quickstart.md](quickstart.md) §3, and installs its id and secret in the test site's private settings. Nothing goes in the repository; the tick says only that it is done. +- [ ] T002 The maintainer answers the spec's three open questions (FR-016 revocation, FR-022 sandbox Person, FR-023 claim records); the answers replace the `[NEEDS CLARIFICATION]` markers in [spec.md](spec.md) and are recorded in [research.md](research.md) (R5, R11, R10), and the register's open-decision entries are closed. +- [ ] T003 Read ORCID's current public documentation (no request from code or tests) and record in research: whether the Member API checks PKCE for a confidential client (R4), the revocation endpoint and its parameters (R5), v3.0's bulk-add limit and v2.x's retirement (R6), whether `/activities/update` reads the works Reactome added (R7), and the Member API's rate limits (R9). Correct [contracts/orcid-works.md](contracts/orcid-works.md) where it differs. + +## Phase 2: Foundational (types, settings, the stub, shared modules) + +- [ ] T004 [P] Add `projects/contract/orcid.ts` with `OrcidStatus`, `ClaimingSummary`, `OrcidWork`, `OrcidContactText`, `OrcidError` and `OrcidErrorCode` ([data-model.md](data-model.md)); rows in `projects/contract/routes.ts` for the JSON routes; regenerate `projects/contract/openapi.json` with notes written from [contracts/endpoints.md](contracts/endpoints.md) (Java's documentation has none for these). +- [ ] T005 [P] [US4] Add the ORCID settings to `tools/content-node/settings.ts` and the enabled rule (R8): on only when every setting is present and valid; production hosts refused without `ORCID_PRODUCTION=1`; loopback refused without `ORCID_STUB=1`; one start-up line naming a missing setting, never a value. C16. +- [ ] T006 [P] Add `tools/orcid-stub/stub.ts`, exporting `startStubOrcid()` (no side effect on load; joins `tools/load.spec.ts`'s `SERVICES`): the authorise page (approve, decline, a chosen placeholder account), token (checks client, secret, redirect URI, code, single use, and `code_verifier` when a challenge was sent), revoke, works GET and bulk POST (validates every body against [contracts/orcid-works.md](contracts/orcid-works.md), answers conflicts for works it already holds, keeps tallies), and failure modes on demand (401, 500, a slow answer). Listens on loopback only. A spec of its own shows a malformed work refused. +- [ ] T007 [P] Placeholder fixtures: the stub's accounts (`Placeholder Researcher`, iDs from ORCID's documented examples or the stub's reserved range) and fixture Persons with placeholder names and free text, with a check over `tools/content-node/fixtures/orcid*` and `e2e/**/orcid*` that every iD and name is on an allowlist. C27. +- [ ] T008 Add `tools/content-node/orcid-client.ts`: token exchange, revoke, bulk add, works list; HTTPS verified by name; refuses any host but the configured ones before sending; 30-second limits; no logging of bodies. C17. +- [ ] T009 [P] Add `tools/content-node/sessions.ts`: the store (R3), pending sign-ins, cookie writing and reading, idle and absolute limits on an injected clock, identifier rotation, the 10,000 cap, and the family's `Cache-Control: no-store` helper. C6, C7, C22. +- [ ] T010 Move the Person lookup (`personWhere`) and the four lists' query out of `person-endpoints.ts` into `tools/content-node/person-lists.ts`, so the ORCID family can read them without importing another family; `scripts/check-move.mjs` must report a pure move, and the person answers stay byte-identical (parity run before and after). + +**Checkpoint**: nothing is routed yet; every shared piece has its checks. + +## Phase 3: User Story 1 - Sign in with ORCID (P1) + +- [ ] T011 [US1] Add `tools/content-node/orcid-endpoints.ts` with `login`, register the family in `registry.ts` and `fixtures/route-order.json`, and keep `boundaries.spec.ts` green. C1, C5. +- [ ] T012 [US1] The callback at both addresses: `state` check, server-side exchange, new session, the 302 to `/orcid-callback` with `outcome`, `Referrer-Policy: no-referrer`; `/orcid/token` stays unserved. C2, C3, C4. +- [ ] T013 [US1] `authenticated` (with `enabled`), `signout` (POST, same-origin, revocation per T002), and the family-wide `Origin` check for POSTs. C8, C15. + +**Checkpoint**: sign-in and sign-out work against the stub through the service. + +## Phase 4: User Story 2 - Claim your works (P1) + +- [ ] T014 [US2] Add `tools/content-node/orcid-works.ts`: `SimpleEvent` → work ([contracts/orcid-works.md](contracts/orcid-works.md)), the authored-and-reviewed intersection, batching by 100, and the summary from ORCID's bulk answers. C11. +- [ ] T015 [US2] The five claim routes: checks in the order of [contracts/endpoints.md](contracts/endpoints.md), one claim per session, ORCID's 401 ending the session, 502 and 504 naming how many were added, the 5-minute budget. C9, C10, C12, C13, C14. +- [ ] T016 [US2] Log audit: run the whole ORCID suite with the service's log captured and fail on any of the stub's secrets, codes, tokens, `state`s, session ids, iDs or names. C18. + +**Checkpoint**: a claim against the stub produces the right works and the right summary. + +## Phase 5: User Stories 3 and 5 - Let us know, works, and the record of claims + +- [ ] T017 [US5] Claim records, as T002 decides FR-023: if the report webapp, add the claim-register call to `report.ts` (fire and forget, Java's codes in the log, never the iD), one record per added work, no token and no sign-in record. C19. +- [ ] T018 [P] [US3] `let-us-know-your-orcid` with the optional `person`. C20. +- [ ] T019 [P] [US2] `{orcid}/works`, narrowed to Reactome-sourced works. C21. + +## Phase 6: Routing + +- [ ] T020 [US4] nginx: the two locations in `deploy/nginx/common/routes.conf` (budget `orcid_rate`, `access_log off` on the callback, 330-second read timeout on claims), the zone in each environment file, the dev proxy's two entries, `routes.spec.ts` for the zone and the agreement; run `deploy/nginx/test-config.sh`. C23. + +## Phase 7: The site + +- [ ] T021 [US1] The `/orcid-callback` route: each outcome's words (signed in; declined; failed, with the cookie hint for `reason=state`), and the return to the Person page only when `return` is a site path. C25. +- [ ] T022 [US1] [US2] The Person page's controls (FR-029), driven by `authenticated` and the page's ORCID iD; nothing when disabled. C24. +- [ ] T023 [US2] Claim confirmation with the count, the working state, the summary dialog (with a link to the researcher's ORCID record), and each error's `user-message`; 401 offers sign-in again. C26. +- [ ] T024 [US3] "Let us know your ORCID": the form (name, e-mail, the pre-filled subject and message, Turnstile) posting to `POST /ContentService/contact`. +- [ ] T025 The privacy notice's paragraph on the ORCID sign-in (FR-027), for the maintainer's approval before the feature is offered on the test site; the user guide's `claim-your-work.mdx` text for the redirect flow (screenshots wait for the curator's). + +## Phase 8: The whole flow, and the sandbox + +- [ ] T026 A whole-flow test: the real server and the stub, a cookie-keeping client following every redirect from `login` through the stub's authorise page and the callback to a claim, a second claim (all conflicts) and sign-out. +- [ ] T027 [US4] After T001 and T002: deploy on the test site with the sandbox settings and walk [quickstart.md](quickstart.md) §3 (SC-001); record the outcome here, without iDs, names or host names. Check also that the old works' links (`/content/detail/{stId}`, `/PathwayBrowser/#/{stId}`) open the right pages on the new site. +- [ ] T028 Close out: tick spec 006's T110 with this spec's PRs; register rows to "live on beta"; `RELEASE-TESTING.md` and `CURATOR-REPORT.md` rows for the claim flow (**auto** naming T026's and the site's specs, **human** for the sandbox walk). + +## Dependencies + +- T001 and T002 gate T027 only; everything else is built against the stub. T002 decides the substance of T013's revocation, T017 and the `ORCID_TEST_PERSON` part of T005. +- T004–T010 before Phase 3. T011 → T012 → T013. T014 before T015. T015 before T016, T017, T019. T011 before T020. Phase 7 needs only T004 (it answers the service's routes itself), so it can run beside Phases 3–6. +- T026 after T020; T027 after everything but T028. + +## Parallel opportunities + +T004, T005, T006, T007 and T009 touch different files. T018 and T019 likewise. The site's tasks (T021–T025) can run beside the service's once T004 is in. + +## Out of scope + +Production credentials (an update of the existing production client's secret, by the maintainer), switching production on, updating or deleting works already claimed, claiming from pages other than the Person page, and replacing the report webapp.