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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 25 additions & 2 deletions documentation/declared-differences.md
Original file line number Diff line number Diff line change
Expand Up @@ -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**

Expand Down Expand Up @@ -44,14 +44,15 @@ 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 |
| [BioPAX (BioPAX3Exporter)](#biopax-biopax3exporter) | 13 | Exporter merged; website endpoint live on beta |
| [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).
Expand Down Expand Up @@ -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 |
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion specs/006-content-service-to-node/tasks.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
36 changes: 36 additions & 0 deletions specs/031-orcid-claim/checklists/requirements.md
Original file line number Diff line number Diff line change
@@ -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.
Loading
Loading