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

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 74 additions & 0 deletions .context/decisions/0030-compute-pages-follow-adr-0010-phase-3.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# ADR 0030: Compute pages are ADR 0010's Phase 3, behind a grant of their own, and decide nothing

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

## Context

ADR 0010 split access into a base tier and a service tier and left "the compute/service features the grant unlocks" as Phase 3.
nemar-cli's Epic D (#2021) has now built the backend half: a compute-access grant (`users.compute_access`, ADR 0118 there), the person's one request, the administrators' decisions, and a user API.
Epic E (website#493) is the web half, and its first phase (website#494) puts the request and its state in Settings.
Several things had to be settled before any compute page could be written: whether compute access is a tier or a grant, who decides, where the pages live, and how the website learns words and numbers it must not retype.

## Decision

**Compute pages are ADR 0010's Phase 3.** They are a front end over nemar-cli's `/compute` routes and decide nothing: not who may request, not what a state means, not what a balance is.
Every state, date, refusal and sentence is the backend's, and the website renders it.

**Compute access is its own grant, `compute_access`, never derived from `service_access`.**
nemar-cli ADR 0040 keeps `service_access` as the upload grant and makes admin approval its single writer; compute is reviewed separately and spends a finite allocation, so it has a column, a request and a decision of its own.
The session user carries `compute_access`, `compute_access_requested_at` and `compute_access_granted_at` as optional fields that are never defaulted: absent means the backend cannot say, and the Settings card then renders nothing rather than "Not requested".
A state outside the closed six (`none`, `requested`, `active`, `suspended`, `denied`, `revoked`) is dropped at the parser for the same reason.

**Compute pages live on the app host only** (ADR 0006), next to Settings and the dashboard; the marketing host links to docs, not to a compute surface.

**Charts are hand-rolled in SVG** (ADR 0007) when the dashboard phase needs them.
Untrusted text a compute page shows (a purpose, a job name, a log line) renders as inert text, as ADR 0029 requires of the mail tab.

**Copy and gap rules are transcribed, not imported** (ADR 0015).
The 27 non-`cli.` compute keys, the `compute_access` gap block, the block order `verified, upload_access, compute_access, publication` and the `affiliation` row (which blocks compute access alone) are copied from nemar-cli commit 3a869903 and pinned by the existing drift test.
The profile-gap list is no longer one list for every surface: the dashboard nudge and Settings' account list drop gaps that stop compute access and nothing else (`withoutComputeOnlyGaps`), so an account that never asked for compute is not nagged about Affiliation.
The field's tag in Settings reads "needed to request compute access" only on a page where the compute card renders, and a refusal's list is worded for compute through a `block` override on `gapsForFields` (without it, an unproven ORCID iD would read "needed to request upload access" under a compute refusal).

**The refusal list is one function** (`src/lib/refusal-list.ts`), called by both request cards; the upload card's inline loop is gone.

**Two interim decisions, each removed when nemar-cli's phase D2 lands.**

1. The current terms version is transcribed into `src/lib/compute-terms.ts` (`2026-11-draft`).
The intended route is `current_terms_version` from `GET /compute/me`, served by D2.
`test/compute-terms-contract-drift.test.ts` compares the constant with nemar-cli's `shared/contract/compute-terms.ts` and is strict in CI (`NEMAR_CLI_COMPUTE_ACCESS_CONTRACT`); CI pairs with nemar-cli `dev`.
A stale version is not silent: the backend answers `terms_not_accepted` and the card prints it.
2. Requests are open only where they can succeed.
`COMPUTE_REQUESTS_ENABLED` is `false` in the production build while the terms are a held draft, and `computeRequestsOpen` also opens the form against any backend that is not the production API (`PUBLIC_API_BASE_URL`), because those backends take requests whether or not the terms are published.
It is deliberately not keyed on the dev-server flag: a bare `bun run dev` shows the production-like inert card.

**Hand-off for the follow-up that replaces both interim decisions.**
nemar-cli phase D2 (PR 2072) serves `GET /compute/me`, whose `access` object carries `state`, `requested_at`, `granted_at`, `terms_version`, `current_terms_version`, `terms_published` and, where it is sent, `requests_open`.
Once it is merged, one change (not this phase, because the route is not on the branch this phase builds against) reads it server-side in the Settings frontmatter, over `dashboardApiBase` with the visitor's cookie, and then:
(a) takes the version printed beside the checkbox and sent as `accept_terms_version` from `access.current_terms_version`, which removes `src/lib/compute-terms.ts`, `data-terms-version`'s constant and `test/compute-terms-contract-drift.test.ts` (and its CI sparse-checkout path and variable), and ends the stale-version failure (a baked version after a backend bump gets `terms_not_accepted` with the box checked);
(b) decides whether the form shows from `access.requests_open` (falling back to `access.terms_published`), which removes `COMPUTE_REQUESTS_ENABLED`, `computeRequestsOpen` and the flag tests; and
(c) decides what to show when the read fails: the card keeps the state from `/auth/me` and shows no form, never a guess.
The captured fixtures in `test/fixtures/compute/` gain a `GET /compute/me` capture at that point.

## Consequences

- A compute sentence is never typed in a page; `test/compute-access-ui.test.ts` fails if one is.
- Until the compute epic merges to nemar-cli `dev`, the website's copy drift test and the new contract drift test are red on any website branch that CI pairs with `dev`; the keys must not reach website `staging` before then, or every nemar-cli pull request goes red.
- The card needs a backend that sends `compute_access`; against an older one it is absent, by design.
- The affiliation gap now exists on the admin review card for upload requests ("blocks compute access"); it does not change what an upload request is refused for.
- A request whose admin mail failed cannot be re-sent from the web (the card shows no form once the state is `requested`); the CLI re-sends it.
- Local verification against the real backend is possible: `scripts/local-backend.mjs`, documented in `.context/local-backend.md`.

## Alternatives considered

- **Treat compute as a third tier derived from `service_access`.** Rejected: it would couple two reviews that nemar-cli deliberately decides apart, and make the website guess a grant the backend states.
- **Default an absent `compute_access` to `none`.** Rejected: an older backend would show "Not requested" and invite a request it will refuse.
- **Import nemar-cli's contract.** Rejected for the reason ADR 0015 gives.
- **Read the terms version server-side in the page frontmatter now.** Not available until D2 serves `GET /compute/me`; the transcription and its drift test are the bridge.
- **Show the backend's sentence for the profile refusals.** Rejected: it lists raw field names (`given_name, affiliation`); the linked, worded list is what the CLI prints.

## Receipts

- website#493 (epic), website#494 (phase E1); nemar-cli#2021 (Epic D), #2071 (phase D1, commit 3a869903).
- ADRs 0006, 0007, 0010, 0014, 0015, 0029; nemar-cli ADRs 0040, 0042, 0118.
1 change: 1 addition & 0 deletions .context/decisions/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,3 +61,4 @@ Add new entries here as you create ADRs:
- ADR 0027 - [The admin approval page prints the API's review words and computes no verdict](0027-the-admin-approval-page-prints-the-apis-review-words.md) (accepted)
- ADR 0028 - [The BIDS validator runs in the browser from a vendored bundle, in a worker](0028-bids-validator-vendored-bundle-in-a-worker.md) (accepted)
- ADR 0029 - [The admin Mail tab renders email as inert text and sends every reply under one key per draft](0029-admin-mail-tab-untrusted-text-and-reply-keys.md) (accepted)
- ADR 0030 - [Compute pages are ADR 0010's Phase 3, behind a grant of their own, and decide nothing](0030-compute-pages-follow-adr-0010-phase-3.md) (accepted)
12 changes: 11 additions & 1 deletion .context/handoff.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,16 @@
# Handoff — nemar.org website

**Last session:** 2026-10-27.
**Last session:** 2026-11-06.

## 2026-11-06: Compute access card in Settings (website#494, epic website#493 phase E1)

Branch `feature/issue-494-compute-access-card`, PR into the epic branch `feature/issue-493-epic-compute-web` (not `staging`). ADR 0030.

- **Recipe for the next phase:** run the real backend with `NEMAR_CLI_DIR=<nemar-cli Epic D checkout> bun scripts/local-backend.mjs`, then `PUBLIC_API_BASE_URL=http://localhost:8787 bun run dev`; `.context/local-backend.md` has the cookie steps. Fixtures are captured, not written: `scripts/capture-compute-fixtures.mjs` writes `test/fixtures/compute/`.
- **Where the keys come from:** nemar-cli commit `3a869903` (phase D1, squash on `feature/issue-2021-epic-compute-users`): 27 copy keys, the `compute_access` gap block, the `affiliation` row, `COMPUTE_TERMS_VERSION`.
- **Gates:** drift against that checkout passes locally (`NEMAR_CLI_ACCOUNT_COPY=<checkout>/shared/contract/account-copy.ts`, `NEMAR_CLI_COMPUTE_ACCESS_CONTRACT=<checkout>/shared/contract/compute-terms.ts`). In CI both are red until the compute epic is on nemar-cli `dev`; the CI ref stays `dev`. Never put these keys on `staging` before then.
- **When D2 lands:** delete `src/lib/compute-terms.ts` and its drift test, and read `current_terms_version` from `GET /compute/me` in the page frontmatter; `COMPUTE_REQUESTS_ENABLED` flips with the published terms, in a reviewed change.
- **Open:** the terms page (`/policies/compute-terms/`) is a held draft, so the link 404s on staging until docs publish. The active state's body mentions the compute page; the link comes with E2.

## 2026-10-27: The mirror chip follows the API flag (website#478, PR #489)

Expand Down
65 changes: 65 additions & 0 deletions .context/local-backend.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# Running the website against a local nemar-cli backend

Worked on 2026-11-06 (website#494). It runs the real backend, not a stand-in:
`scripts/local-backend.mjs` imports nemar-cli's own Worker entry point, its real migrations over a
`bun:sqlite` database, and its real session issuance, and serves them with `Bun.serve`. The only
additions are the platform's: an `ExecutionContext`, and the backend's documented `X-Test-Bypass`
for its rate limiter (which needs the Cloudflare Cache API that bun lacks).

## Safety

The server listens on `127.0.0.1` only (`Bun.serve({ hostname })`; without it bun binds every
interface). It adds `X-Test-Bypass` to every request and prints a fixed owner key, so it is never to
be reachable from another machine. The script refuses to start under a production-like
`ENVIRONMENT` (anything but `test`, `dev`, `development`, `local`), a `BIND_HOST`, `HOST` or
`BUN_HOST` that is not loopback, or a `WEB_ORIGIN` that is not loopback, and exits if the socket it
got is not `127.0.0.1`. `test/local-backend-guard.test.ts` runs the refusals.

## Steps

1. A checkout of the nemar-cli branch to run (for the compute card, the Epic D branch
`feature/issue-2021-epic-compute-users` or any branch after it). Make your own worktree; do not
touch a shared checkout. Run `bun install` at its root and in `backend/`.
2. In this repo:

```bash
NEMAR_CLI_DIR=/path/to/nemar-cli-checkout bun scripts/local-backend.mjs
```

It seeds an owner and nine `@nemar.test` accounts (complete profiles and an ORCID identity row;
one per compute state, plus `noaffiliation`, `noprofile` and `noorcid`, which a request refuses).
For each it signs in through the real `POST /auth/code/request` and `POST /auth/code/verify`
(the dev backend echoes the code for `@nemar.test`), prints the session cookie, and writes them
to `.local-backend/cookies.json` (git-ignored). The database is in memory: a restart resets it.
3. In another terminal:

```bash
PUBLIC_API_BASE_URL=http://localhost:8787 bun run dev
```

The middleware verifies a real cookie against `${PUBLIC_API_BASE_URL}/auth/me`, and the browser's
calls go through the `/api/v1` proxy to the same backend. Localhost is an allowed Origin there.
4. In the browser, on `http://localhost:4321`, set the cookie from the script's output and open
`/settings`: `document.cookie = "nemar_session=<value>; path=/"`. (The development login mock
never reaches the backend; pasting the cookie is what does.) A request made from the card is a
real write; grant it from a terminal with the owner key the script prints:

```bash
curl -s -X POST -H "Authorization: Bearer <owner key>" \
http://localhost:8787/admin/compute/access/grant/localrequested
```

## What differs from production

- `ENVIRONMENT` is `test`: the backend takes compute requests whether or not the terms are
published, and no mail is sent (no mail key is configured). The website shows the request form
because `PUBLIC_API_BASE_URL` is not the production API (`computeRequestsOpen`).
- The CLI keys card in Settings still shows the `astro dev` mock list (it is gated on the dev flag).
- Under `bun run dev` with no `PUBLIC_API_BASE_URL`, the `@nemar.*` personas of `src/lib/auth-dev.ts`
need no backend at all (`@nemar.cnone` and the other compute personas render each state).

## If it breaks

The script fails loudly at the first thing it cannot do (a missing `NEMAR_CLI_DIR`, a missing
`backend/node_modules`, a migration the checkout does not have). Do not substitute a mock backend:
fix the checkout, or escalate with the error.
6 changes: 6 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -119,12 +119,17 @@ jobs:
# test/oidc-authorize-contract-drift.test.ts is a SEVENTH, against
# shared/contract/oidc-authorize.ts (the authorization endpoint's routes, answer kinds, codes
# and reasons) and shared/oidc.ts beside it (the page's path). Same `dev` pairing, and strict.
# test/compute-terms-contract-drift.test.ts is an EIGHTH, against shared/contract/compute-terms.ts:
# the compute terms version a request must name (website ADR 0030, interim until phase D2's
# GET /compute/me serves it). Same `dev` pairing, strict, and red until the compute epic
# reaches nemar-cli `dev`; the ref stays `dev`.
- uses: actions/checkout@v4
with:
repository: nemarOrg/nemar-cli
path: nemar-cli-contract
sparse-checkout: |
/shared/contract/account-copy.ts
/shared/contract/compute-terms.ts
/shared/contract/docs-auth.ts
/shared/contract/mail-admin.ts
/shared/contract/oidc-authorize.ts
Expand All @@ -139,6 +144,7 @@ jobs:
run: bun run test
env:
NEMAR_CLI_ACCOUNT_COPY: nemar-cli-contract/shared/contract/account-copy.ts
NEMAR_CLI_COMPUTE_ACCESS_CONTRACT: nemar-cli-contract/shared/contract/compute-terms.ts
NEMAR_CLI_DOCS_CONTRACT: nemar-cli-contract/shared/contract/docs-auth.ts
NEMAR_CLI_MAIL_ADMIN_CONTRACT: nemar-cli-contract/shared/contract/mail-admin.ts
NEMAR_CLI_OIDC_AUTHORIZE_CONTRACT: nemar-cli-contract/shared/contract/oidc-authorize.ts
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -53,3 +53,4 @@ playwright-report/
# hand-created locally; point NEMAR_CLI_ACCOUNT_COPY at a real checkout
# instead.
nemar-cli-contract/
.local-backend/
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,17 @@ The release pull request from `staging` to `main` moves those entries under the

### Added

- **A compute access card in Settings** (website#494, epic website#493 phase E1; nemar-cli epic #2021 phase D1, ADR 0030).
Beside the upload-access card, `#compute-access` shows the account's compute-access state (not requested, requested, active, suspended, not granted, ended) and, for a verified account that has never asked, a request form: a purpose of 20 to 1,000 characters, a required checkbox for the compute terms (with the version, linking the terms page), and the refusal list a refused request returns, as links to the fields to fix.
Every sentence is a transcribed copy key, the same words the CLI prints.
The card renders only when the backend reports a state; an older backend gets no card, never "Not requested".
The production build shows "not open yet" in place of the form until the compute terms are published (`COMPUTE_REQUESTS_ENABLED`); a build pointed at another backend shows the form.
The Affiliation field is tagged "needed to request compute access" on a page that has the card, and carries the `#profile-affiliation` anchor.
Affiliation is a new gap that stops compute access alone, so the dashboard nudge and Settings' account list leave it out.
The upload card's refusal list and the new one share one renderer.
Needs the nemar-cli backend with the compute epic; `test/compute-terms-contract-drift.test.ts` and the account-copy drift test stay red until it reaches nemar-cli `dev`.
`scripts/local-backend.mjs` runs that backend locally with seeded accounts (see `.context/local-backend.md`); the `astro dev` login has seven compute personas (`@nemar.cnone`, `.creq`, `.cactive`, `.csusp`, `.cdenied`, `.crevoked`, `.cpending`).

- **`/oauth/authorize`, the sign-in page of NEMAR's OpenID Connect provider** (nemarOrg/nemar-cli#2017, nemar-cli ADR 0119).
A site registered with NEMAR sends a person here to sign in with their NEMAR account.
The page forwards the request and the person's cookie to the API, which decides everything, and then redirects back to the site, asks for consent, or explains a refusal.
Expand Down
Loading
Loading