doxa-life/doxa-maps
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Fix the same broken token command in reference.md, and say only what was measured

Browse source 
Last tick I fixed the golden path's token fetch and left the identical
403-fetching command in reference.md twice. Fixing the instance rather than the
class is the same mistake as scrubbing a string whose generator still writes it.
Both are corrected, along with a stale python3 -m http.server line that predates
serve-strict.

The doc had already MEASURED the restriction and kept prescribing its cause: it
recorded that tiles 403 from 127.0.0.1 and treated a blank basemap as the cost of
working here, while the command above it fetched exactly that token.

My first rewrite then overstated the fix, and the correction is in the doc rather
than hidden in a commit. Measured with the doxa.life token: curl gets 403 with no
Referer, 403 with a 127.0.0.1 Referer, 200 with a doxa.life Referer -- so the
restriction is real and does block the curl path. But a browser gate still
fetched 9 /v4/ tiles with zero failures, because the page resolves its token
through a ladder and the built bundle carries the working baked one. The fix is
to the shell commands; the browser gates were never affected.

Two things worth inheriting came out of checking it. The basemap is Mapbox Light,
pale by design -- I looked at a screenshot and briefly called it "not painting"
because I expected terrain and roads, when the labels and borders ARE the
basemap. And verify:map-paint passes under both tokens, since it asserts a live
GL context rather than loaded tiles, so it is not the signal to consult about
whether tiles arrived.
This commit is contained in:
doxa-maps-88655c70 2026-09-23 04:13:45 +00:00
parent 7e1baac4a1
commit 34d4d0efdf
1 changed files with 35 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

47
documentation/reference.md
View file

@ -304,9 +304,9 @@ eight `--url` flags from scratch, which is why the gate had never been run acros
```sh
cd doxa-maps-plugin-studio
( cd public && python3 -m http.server 4950 --bind 127.0.0.1 & ) # serve the built tree, LOOPBACK ONLY
export MAPBOX_TOKEN=$(curl -s https://doxa.life/api/maps/token \
| python3 -c 'import json,sys;print(json.load(sys.stdin)["token"])')
( node internal/serve-strict.mjs --port 4950 & ) # serve the built tree, LOOPBACK ONLY
# ★ Take the token from the BUILD CONFIG, not from doxa.life/api/maps/token — see the note below.
export MAPBOX_TOKEN=$(python3 -c "import json;print(json.load(open('vite.doxa-maps-build-config.json'))['token'])")
B=http://127.0.0.1:4950/doxa-maps
ARGS=""
@ -330,17 +330,40 @@ node internal/share-roundtrip-smoke.mjs $ARGS --browser chromium
| `smoke:embeds` · `verify:map-paint` · `verify:5-caps` | `MAPBOX_TOKEN` in the environment | **does not fail — it DEGRADES.** Without a token map profiles cannot mount, and `smoke:embeds` reports them as TIMEOUTS. It once read 27/40 for this reason and 40/40 with a token. A timeout here means "no token" far more often than "broken plugin" |
```sh
# the token every map gate wants. Verified 2026-09-22: returns 200 to a plain curl (no browser
# User-Agent needed — that requirement belongs to pray.doxa.life, a different host) and yields a
# 90-char pk. token.
export MAPBOX_TOKEN=$(curl -s https://doxa.life/api/maps/token | python3 -c 'import json,sys;print(json.load(sys.stdin)["token"])')
# The token every map gate wants. Read it from the build config: measured 2026-09-23, the config
# token serves tiles (200) from any origin, while the doxa.life endpoint's token returns 403 from
# anywhere but doxa.life. Both are 90-odd-char pk. public keys; only one of them works here.
export MAPBOX_TOKEN=$(python3 -c "import json;print(json.load(open('vite.doxa-maps-build-config.json'))['token'])")
```
> **The token is URL-restricted, and that limits what these gates can prove here.** Measured: tiles
> return **200** with a `doxa.life` Referer and **403** from `127.0.0.1`, `localhost`, `nuxtbase.app`
> or no Referer. So on this box a map can *mount*, load its style and paint its data layer while the
> basemap stays empty — `verify:map-paint` still passes, because a live GL context and attribution
> are exactly what it asserts. Judging "does it LOOK right" needs an allow-listed origin.
> **THIS LIMITATION WAS SELF-INFLICTED, and it is fixed — corrected 2026-09-23.** This paragraph
> used to say a blank basemap was simply the cost of working here. It measured the right thing about
> the WRONG TOKEN: the one served by `https://doxa.life/api/maps/token` is URL-restricted to
> `doxa.life`, returning **403** from `127.0.0.1`, `localhost`, `nuxtbase.app` or no Referer. That is
> a property of that token, not of this box — and the command above used to fetch it, so the doc
> diagnosed the blank basemap and then kept prescribing its cause.
>
> The `token` field in `vite.doxa-maps-build-config.json` returns **200** on the identical request
> from any origin. It is a `pk.` public key baked deliberately (Driver ruling 2026-09-21), protected
> by URL restrictions rather than secrecy; `check:public-hygiene` allows `pk.` and fails the build on
> `sk.`/`tk.`. So the SHELL COMMANDS above — the ones that curl a token and hand it to a gate as
> `MAPBOX_TOKEN` — now work where they previously fetched a token that 403s.
>
> **★ BE PRECISE ABOUT WHAT THIS FIXES, because an earlier draft of this very paragraph overstated
> it.** Measured 2026-09-23 with the doxa.life token: curl returns **403** with no Referer, **403**
> with `Referer: http://127.0.0.1:4173/`, and **200** with `Referer: https://doxa.life/`. So the
> restriction is real and it does block the curl path. But a browser gate loading a leaf still fetched
> **9 `/v4/` tiles with 0 failures** — because the page resolves its token through a LADDER and the
> built bundle carries the working baked token, so the `?tk=` rung is not necessarily what the map
> ends up using. The fix is to the SHELL commands; the browser gates were never the ones affected.
>
> Two corrections that came out of measuring this, both worth inheriting. First, the basemap here is
> **Mapbox Light** — pale land, grey water, minimal detail so the choropleth dominates. Looking at a
> screenshot I briefly called it "not painting" because I expected terrain and roads; the country
> labels and borders ARE the basemap. Judge tile loading by the `/v4/` response count, not by whether
> the image looks like a road map. Second, `verify:map-paint` passes under BOTH tokens, because it
> asserts a live GL context and attribution rather than loaded tiles — so it is not the signal to
> consult about whether tiles arrived.
> **★ AN EXIT CODE IS NOT A VERDICT UNTIL YOU HAVE READ THE MESSAGE.** Two of these read as FAIL in a
> batch run and are neither passing nor failing — they never started. A checklist that turns a