about summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-11-07 14:43:28 +0000
committerPjotr <wrk@bosa.lan>2026-11-07 14:43:40 +0000
commit84838f6e8f42a2a794641bc766f273fbd152e7fd (patch)
treed905b315c64e0f1c1520211538e63204af3c3862 /docs
parentf346dc273ef38cdb268fd68bb5697a8ee30e5fde (diff)
downloadgenenetwork4-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.md65
-rw-r--r--docs/www/operator-checklist.md7
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: