diff options
| author | Pjotr <wrk@bosa.lan> | 2026-11-07 14:43:28 +0000 |
|---|---|---|
| committer | Pjotr <wrk@bosa.lan> | 2026-11-07 14:43:40 +0000 |
| commit | 84838f6e8f42a2a794641bc766f273fbd152e7fd (patch) | |
| tree | d905b315c64e0f1c1520211538e63204af3c3862 /docs | |
| parent | f346dc273ef38cdb268fd68bb5697a8ee30e5fde (diff) | |
| download | genenetwork4-84838f6e8f42a2a794641bc766f273fbd152e7fd.tar.gz | |
docs/www: say who issues tokens, and what the assistant should ask for
The page said a human issues tokens and to "stop and ask", without saying whose door to knock on -- and the operator commands belong in the operator file anyway. State it as the GeneNetwork team, with wording the assistant can relay to its user: what a token is for, how long the default lasts, and to pass it out of band rather than through a public issue or a shared chat. Same wording for renewal, since a 401 is the one failure the assistant cannot fix itself. * docs/www/ai-instruction.md (1. Get a token): "If you do not have one" and "If it stops working", the latter quoting request_id and retrying exactly once; the summary line and the 401 row of the error table say GeneNetwork team rather than "the operator". * docs/www/operator-checklist.md (Token issuance): the request path, so the team knows what the ask they receive looks like. * .gitignore: *.swp, after one got swept into this commit.
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/www/ai-instruction.md | 65 | ||||
| -rw-r--r-- | docs/www/operator-checklist.md | 7 |
2 files changed, 54 insertions, 18 deletions
diff --git a/docs/www/ai-instruction.md b/docs/www/ai-instruction.md index f514577..404731b 100644 --- a/docs/www/ai-instruction.md +++ b/docs/www/ai-instruction.md @@ -14,18 +14,39 @@ Machine-readable description of every endpoint: `GET /gn4/openapi.json`. Endpoint-by-endpoint prose: [`../../README.md`](../../README.md). ``` -1. You are given a token → by the operator, out of band +1. You are given a token → by the GeneNetwork team, out of band 2. Send it on every request → Authorization: Bearer <token> 3. Read JSON, check meta → {"data": ..., "meta": ..., "notes": [...], "next": [...]} ``` ## 1. Get a token -**You cannot mint a token yourself.** Tokens are issued by a human, on -the server, one per user. If you have not been given one in your task -context, stop and ask — do not go looking for a login form, an API key, -or a token endpoint on the public host; there is none -(`POST /gn4/get-test-token` is a deliberate 404). +**A human on the GeneNetwork team has to issue it; you cannot mint one +yourself.** It is not self-service: no sign-up, no login form, no token +endpoint on the public host — `POST /gn4/get-test-token` is a deliberate +`404`, and there is nothing else to authenticate against. + +So, before anything else, look for a token that was already given to you +in your task context. + +### If you do not have one + +Stop and ask the user to get one for you. Say something like: + +> To read GeneNetwork data I need a GeneNetwork API token (a JWT) for +> `https://vesuvio.pu.ac.ke/gn4`. Could you ask the GeneNetwork team to +> issue one for me? It is issued by hand, not self-service. It helps +> them to know who it is for, which species/groups/datasets you need, +> roughly how long you need it (the default is 30 days) and what for. +> Please pass it to me out of band — not in a public issue, a commit or +> a shared chat. + +Then wait for it. Do not guess, invent, reuse a token that was not given +to you, or try another route in: the only unauthenticated endpoints are +`/version` and `/openapi.json`, and everything else answers `401` (no +token) or `404` (not routed). + +### Using it ```sh TOKEN=… # the JWT you were given @@ -33,18 +54,26 @@ API=https://vesuvio.pu.ac.ke/gn4 curl -s -H "Authorization: Bearer $TOKEN" "$API/groups/BXD/traits?limit=1" ``` -The token is a **JWT** whose `exp` is set at mint time (typically 30 -days). Nothing renews it and nothing revokes it early, so: +* Send it on every request, and keep it for the whole session. +* Never put it in a URL, a commit, a log line, or anything you show to + someone else. It is yours: do not hand it to other users or paste it + into shared state — a token identifies whoever holds it. +* It carries no rights of its own. It gets you past the door; what you + may read is decided per dataset (§4), and non-public data answers + `403` whatever token you hold. + +### If it stops working + +A `401` means the token is missing, expired, or was issued for a +different deployment — the `detail` distinguishes `ExpiredSignature` +from `InvalidIssuer`. You cannot renew it, so: -* use it on every request, and keep it for the whole session; -* never put it in a URL, a commit, a log line, or anything you show to - someone else; -* on `401` the token is missing, expired, or was not issued for this - deployment. You cannot fix that yourself: say so, ask for a fresh - token, retry once; -* it carries no rights of its own — it gets you past the door, and what - you may read is decided per dataset (see §4). Anything non-public - answers `403` no matter which token you hold. +1. tell the user the token has expired (or is not accepted) and ask them + to request a fresh one from the GeneNetwork team, using the wording + above and quoting the `request_id` from the error body; +2. retry **once** with the new token when it arrives; +3. if it still fails, stop and report it — do not loop, and do not go + looking for another credential. ## 2. Discover the API, don't guess @@ -151,7 +180,7 @@ Errors are RFC 7807-style JSON (`type`, `title`, `status`, `code`, | status | code (typical) | do | |---|---|---| -| 401 | `invalid_token` | expired/invalid token (the `detail` distinguishes `ExpiredSignature` from `InvalidIssuer`); you cannot mint one — ask the operator, retry once | +| 401 | `invalid_token` | expired/invalid token (the `detail` distinguishes `ExpiredSignature` from `InvalidIssuer`); you cannot renew it — ask the user to request a fresh one from the GeneNetwork team (§1), then retry once | | 403 | `forbidden` | the data is not public: do not retry | | 404 | `not_found` | check the name; `next` often lists the valid values | | 422 | `invalid_query`, `invalid_lmm` | fix the query or parameter; do not retry | diff --git a/docs/www/operator-checklist.md b/docs/www/operator-checklist.md index 583983e..629df7b 100644 --- a/docs/www/operator-checklist.md +++ b/docs/www/operator-checklist.md @@ -47,6 +47,13 @@ xapian index XAPIAN_DB_PATH ## Token issuance (no gn-auth: the stub, one token per user) +The request path is: the AI assistant has no token, so it asks the user +(see §1 of [`ai-instruction.md`](ai-instruction.md)); the user asks the +GeneNetwork team; someone here mints a token for that user and hands it +back out of band; the user passes it to the assistant. Expect the +request to say who it is for, what data, and for how long — that is what +`--subject` and `--expires-in` need. + Run the stub once and leave it running, supervised like genenetwork4 — see "Tokens are stateless" in the README for why an hour of downtime is survivable and longer is not: |
