Closes#1532.
## What
Implements the triage's 3-step fix path + tufte keyboard shortcut:
1. **`.live-controls` collapsed by default at all viewports** (was
≤768px only). The existing ⚙ pin reveals the toggles row on demand —
parity with the map-controls accordion pattern in `map.js`.
2. **New `#liveFullscreenToggle` button (⛶) next to ⚙.** Click or press
`F` to flip `body.live-fullscreen`. CSS under that class hides:
- `.live-header-body` (title)
- `.live-controls-body` (toggle row contents)
- `.vcr-controls` and `.vcr-bar` (timeline scrubber)
- `.bottom-nav`
- secondary panels (`.live-feed`, `.live-legend`, related show-buttons)
3. **`.live-stats-row` stays pinned top-right** with translucent chip
styling so the 3 KPI pills (nodes / active / pkts·min) earn permanent
residence per the tufte finding.
## Tufte rationale (from triage)
> data-ink ratio is poor — 11 controls + 3 KPIs displayed permanently
steal pixels from THE data (the firework animation). Defaults-on chrome
should collapse behind a pin/cog; only the 3 stat pills earn permanent
residence (sparkline-grade density). … "Fullscreen" is the right
primitive — Tufte's "shrink principle" says strip until unreadable, then
add back.
## Keyboard shortcut
`F` toggles fullscreen. Guards:
- Skips when focus is in `INPUT`/`TEXTAREA`/`SELECT`/contenteditable (no
interference with node-filter / audio sliders typing).
- Skips when modifier keys are held.
- Only fires on the `.live-page` route.
- State persists across reloads via `localStorage('live-fullscreen')`.
## TDD
| Commit | SHA | What |
|--------|-----|------|
| RED | `852a474b` | Source-invariant assertion test
`test-issue-1532-live-fullscreen.js` (17 assertions, all fail against
master). |
| GREEN | `906c6cc0` | Implementation: HTML button, JS click+keydown
wiring, CSS body-class rules + top-level `.is-collapsed` rule. |
Verify the RED commit gates the change:
```
git checkout 852a474b -- test-issue-1532-live-fullscreen.js
git checkout master -- public/live.js public/live.css
node test-issue-1532-live-fullscreen.js # exits 1, 15 failures
```
## Files modified
- `public/live.js` — `#liveFullscreenToggle` button in `init()`
template; `wireLiveFullscreenToggle()` IIFE (click + keydown +
localStorage); `wireLiveCollapseToggles()` updated so `liveControls`
defaults collapsed at all viewports.
- `public/live.css` — top-level `.live-controls.is-collapsed` rule;
`body.live-fullscreen { ... }` block hiding chrome and pinning the stats
row.
- `test-issue-1532-live-fullscreen.js` — new source-invariant test (17
assertions across 5 categories).
- `test-all.sh` + `.github/workflows/deploy.yml` — register the new test
in the unit-test runner.
## CDP-verify
Source-invariant assertions cover the behavior gate. The visual diff
cannot run against staging (staging is pre-merge; deploy is
post-master). Local server stand-up was skipped for token-budget
reasons; the assertion test asserts class names + computed-style trigger
conditions equivalent to what a CDP getComputedStyle check would assert.
Post-merge: staging deploy auto-publishes within minutes — visual diff
will land then.
## Preflight overrides
None — preflight clean (PII clean, scope: 5 files all within stated
surface, red→green visible, CSS vars defined, no XSS sinks added).
---------
Co-authored-by: corescope-bot <bot@corescope.local>
Co-authored-by: meshcore-bot <bot@meshcore.local>
## Summary
Follow-up to PR #1569 (merged). Adds defense-in-depth at the DB layer
for the #1534 default_scope-overwrite class of bug.
PR #1569fixed#1534 by guarding the call site in `handleMessage` with
`if shouldUpdateDefaultScope(pktData)`. Adversarial review of #1569
flagged this as one-layer defense: a future refactor that drops the
call-site `if` and calls `store.UpdateNodeDefaultScope(pubkey,
pktData.ScopeName)` unconditionally would silently re-introduce the bug
— overwriting a previously-correct `default_scope` (e.g. `#belgium`)
with the empty string.
This PR adds the belt-and-braces guard recommended by that review:
- `Store.UpdateNodeDefaultScope(pk, "")` is now a silent no-op (early
`return nil`)
- New DB-layer regression test that fails on `master` and proves the DB
function used to write `""` straight through
- Two new call-site anchor tests that drive a transport-scoped ADVERT
end-to-end through `handleMessage` (matched + unmatched region key) so
the existing call-site guard from #1569 can't be deleted without a test
going red
Net production change: 8 lines in `cmd/ingestor/db.go`. No behavior
change for any non-empty scope.
## Why this is a follow-up, not a re-fix
Issue #1534 is already closed by #1569 and `master` no longer regresses
for users (the call-site guard is in place). This PR is purely
belt-and-braces — it adds the second layer of defense the adversarial
reviewer asked for and the test coverage that anchors both layers.
## Files changed
| File | Change |
|------|--------|
| `cmd/ingestor/db.go` | +8 — empty-scope early return in
`UpdateNodeDefaultScope` |
| `cmd/ingestor/db_test.go` | +43 —
`TestUpdateNodeDefaultScope_EmptyScopeIsNoop` |
| `cmd/ingestor/main_test.go` | +97 —
`TestHandleMessageAdvert_EmptyScopeSkipsDefaultScopeUpdate` +
`TestHandleMessageAdvert_MatchedScopeUpdatesDefaultScope` |
## Red → green commits
- **red** `c062af59` — `test(ingestor): red — DB-layer empty-scope guard
regression test for #1534`
- Adds three tests; `TestUpdateNodeDefaultScope_EmptyScopeIsNoop` fails
on assertion (`default_scope` overwritten with `""`)
- Two call-site tests pass already (call-site guard merged in #1569) —
they anchor that behavior against future refactors
- **green** `7ab12d53` — `fix(ingestor): defense-in-depth empty-scope
guard in UpdateNodeDefaultScope (#1534)`
- Adds the early-return; all three tests green
## Operator remediation (from issue #1534)
Operators whose production DB still has rows where `default_scope` was
overwritten with the empty string before #1569 deployed can clean up
with:
```sql
-- Inspect affected rows first
SELECT public_key, name, default_scope
FROM nodes
WHERE default_scope = '';
SELECT public_key, name, default_scope
FROM inactive_nodes
WHERE default_scope = '';
-- Convert empty-string default_scope back to NULL so the next valid
-- matched-scope advert can re-populate it cleanly.
UPDATE nodes
SET default_scope = NULL
WHERE default_scope = '';
UPDATE inactive_nodes
SET default_scope = NULL
WHERE default_scope = '';
```
After #1569 + this PR are deployed, no new rows can be created with
`default_scope = ''` from this code path.
## Test plan
```bash
cd cmd/ingestor && go test ./... -count=1
# ok github.com/corescope/ingestor ~98s
```
## Preflight
Clean — PII, branch scope, red commit, CSS-var defined, CSS
self-fallback, LIKE-on-JSON, sync migration, async-migration gate, XSS
sinks all pass. No warnings.
---------
Co-authored-by: Kpa-clawbot <bot@meshcore-analyzer>
## Summary
Closes#1504. Adds a tiny, dismissible "Path symbols" legend next to the
Path column header on the Packets page (and reused on the Nodes page's
"Paths Through This Node" card), explaining the three
otherwise-undiscoverable path glyphs:
- `⚠N` — regional conflict count (multiple candidates for the hop's
prefix in this region)
- `⚠️` — unreliable name resolution (best-guess pubkey couldn't be
confirmed)
- dashed underline — ambiguous / global-fallback resolution
## Rationale (from triage)
- **Tufte**: integrate words and graphics. A hidden per-row tooltip
violates "don't make the viewer cross-reference." A small, persistent
inline key next to the column header is dense, on-data, and dismissible.
- **Avoid a modal** — chartjunk for a 3-glyph vocabulary.
- **Munger** rejected the reporter's option #2 (hover overlay that
pauses live updates): a power-user table must not stall from accidental
hovers.
- Single shared constant on `HopDisplay` so the Nodes page reuses the
same vocabulary without drift.
## Files
- `public/hop-display.js` — export `PATH_SYMBOLS_LEGEND` constant +
`renderPathSymbolsLegend()` helper (no changes to existing badge
rendering logic)
- `public/packets.js` — wire renderer into the Path `<th>` header
- `public/nodes.js` — reuse renderer on `#fullPathsSection` h4
- `public/style.css` — minimal styling (subtle dotted-underline trigger
+ floating disclosure panel, all via theme vars)
- `test-frontend-helpers.js` — 5 new assertions (TDD red→green)
## TDD red → green
- RED commit `46741267` — adds 5 assertion-shaped tests; all fail on the
assertion (not on import/build).
- GREEN commit `fab27ec5` — implements the constant, renderer, wiring,
and CSS; all 607 frontend-helper tests pass.
## Tested via
- DOM-grep assertions on the rendered `<details>` markup (`<summary>Path
symbols</summary>`, all three glyphs present, dashed-underline
description).
- Static grep that `packets.js` invokes the shared renderer adjacent to
the Path column.
- Full `test-frontend-helpers.js`, `test-packet-filter.js`,
`test-aging.js` pass.
## Hard rules honored
- No modal, no pause-on-hover, no changes to `hop-display.js`'s badge
rendering logic.
- No `<img>`/SVG additions, no new CSS vars (uses existing theme vars),
no Go changes.
- PII grep clean on every commit and on this body.
Browser verified: manual smoke pending — disclosure is closed-by-default
and uses standard `<details>` semantics; renders inline with column
header.
E2E assertion added: `test-frontend-helpers.js` — `#1504:
renderPathSymbolsLegend returns <details> disclosure with "Path symbols"
summary + all glyphs` (and 4 sibling assertions).
---------
Co-authored-by: Kpa-clawbot <bot@meshcore-analyzer>
Co-authored-by: clawbot <bot@openclaw.local>
Red commit: e5668585daFixes#1534
## Problem
`cmd/ingestor/main.go:720` called `UpdateNodeDefaultScope` whenever a
packet was transport-scoped (`IsTransportScoped == true`), without
checking whether `matchScope()` actually returned a region match.
Transport-scoped adverts from non-matching regions carry `ScopeName=""`,
which then overwrote previously-correct `nodes.default_scope` values
with the empty string — surfacing as "unknown scope" / "--" in the node
sidebar.
## Fix
Extracted the guard into `shouldUpdateDefaultScope(pktData)` and added
the non-empty `ScopeName` check:
```go
return pktData.IsTransportScoped && pktData.ScopeName != ""
```
## TDD
- Red commit (`e5668585`): adds
`TestBuildPacketDataScopeMatchingNoMatch` + helper that mirrors the
buggy guard. CI must fail on assertion.
- Green commit (`aab7f5d7`): adds the `ScopeName != ""` check. Test
passes.
## Out of scope (deferred)
- The optional one-time backfill / migration marker removal described in
the issue — new matching adverts will self-correct existing rows.
- Refactor of `IsTransportScoped` + `ScopeName` into a typed wrapper.
## Files
- `cmd/ingestor/main.go` — guard + new helper
- `cmd/ingestor/main_test.go` — regression test
## Preflight
`bash ~/.openclaw/skills/pr-preflight/scripts/run-all.sh origin/master`
— clean.
---------
Co-authored-by: corescope-bot <bot@corescope.local>
## Summary
Fixes the move-panel corner-cycle button silently no-op'ing after a
panel is dragged on `/live`.
Two coexisting positioning systems were mutating disjoint state:
- `public/drag-manager.js` sets inline
`top/left/right/bottom/transform/position`, stamps
`data-dragged="true"`, and persists `localStorage['panel-drag-<id>']`.
- `public/live.js` `applyPanelPosition()` only flips the `data-position`
attribute (selecting a `.live-overlay[data-position="…"]` rule with
`top/left/right/bottom`).
Inline styles win the cascade, so after any drag the corner button
updated the glyph but the panel never moved. The fix has `onCornerClick`
clear drag state (attribute, inline coords, localStorage) before calling
`applyPanelPosition`.
## Commits
- Red: `ea2f8009` — `test(live): failing E2E for corner-cycle button
after drag (#1567)` — Playwright test injects DragManager-shaped drag
state on `#liveFeed`, clicks `.panel-corner-btn`, asserts
`data-dragged`/inline styles/`localStorage` are cleared AND
`getBoundingClientRect()` matches the CSS corner anchor (not the dragged
coords). Fails on master at the post-click assertion.
- Green: `abb5a21f` — `fix(live): corner-cycle button clears drag state
(#1567)` — 11-line change in `onCornerClick`, plus new E2E wired into
the workflow.
## Files
- `public/live.js` — `onCornerClick` clears `data-dragged`, inline
`top/left/right/bottom/transform/position`, and
`localStorage['panel-drag-<id>']` before `applyPanelPosition`.
- `test-issue-1567-corner-clears-drag-e2e.js` — new Playwright E2E
(drag-state injection + post-click rect assertion).
- `.github/workflows/deploy.yml` — runs the new E2E next to
`test-drag-manager-e2e.js`.
## E2E
E2E assertion added: `test-issue-1567-corner-clears-drag-e2e.js:108`
(post-click drag-state + anchor-match assertions).
Browser verified: red-on-master gated by assertion (`'data-dragged must
be cleared after corner click'`) — green commit makes it pass.
## Scope
- No changes to `drag-manager.js` (out of scope per triage fix path).
- No config / API surface changes.
- Desktop drag path only; mobile / coarse-pointer path unchanged (drag
is gated off there at `live.js:1941`, so the button was always the only
repositioning affordance on touch — preserved).
Partial fix for #1567 — addresses the corner-button-no-op symptom called
out in triage; leaves the issue open for the user to verify in the
browser and close.
---------
Co-authored-by: Kpa-clawbot <bot@openclaw.local>
Co-authored-by: mc-bot <bot@meshcore.local>
Closes#1562. Follow-up to #1551 and #1552.
## Problem
On CDN-fronted deployments (e.g. meshcore.meshat.se), the observers page
header rendered totals computed entirely client-side from a
possibly-stale `/api/observers` response. Operators saw e.g. `0 Online /
43 Stale / 37 Offline` while a cache-busted request returned `44 Online
/ 0 Stale / 36 Offline` — the aggregate row was the first thing they
looked at to assess mesh health, so wrong numbers meant wrong actions.
#1551 added `Cache-Control: no-store` on `/api/*` responses, but the
client also has its own in-memory cache (`api(path, { ttl })`), and
there was no UI signal at all that the rendered counts could be stale.
## Fix scope (Option 3 + light Option 2)
Per the issue's three options, this PR implements **Option 3**
(timestamp label) and a light **Option 2** (manual-refresh button
bypasses client cache). Option 1 (a new server-side
`/api/observers/summary` endpoint) is **deferred** as a follow-up — it's
the most correct fix, but a bigger lift than what's needed to stop
operators from acting on silently-wrong numbers.
## Changes
- **`public/observers.js`**
- New `window.ObserversSummary` pure helper exposing
`computeCounts(observers)` and `renderHeader(counts, fetchedAt)`. Pure
functions = easy to unit test.
- Track `_fetchedAt` (ms) on each successful `loadObservers()` response.
- `render()` delegates header HTML to
`ObserversSummary.renderHeader(counts, fetchedAt)`. Existing aggregate
display (`Online / Stale / Offline / Total`) is preserved exactly — the
only visible additions are the "Last updated: Xs ago" label and a
warning class when the timestamp is >60s old.
- Manual refresh button now passes `{ bust: true }` to `api()` so the
operator can force a fresh fetch when they suspect staleness.
- **`public/style.css`**
- New `.obs-updated` and `.obs-updated-stale` rules using existing
`--text-muted` / `--warning` CSS variables (no new colors).
- **`test-issue-1562-observers-summary.js`** +
**`.github/workflows/deploy.yml`**
- Unit tests for `computeCounts` (mixed ages → 1/1/1 + total),
`renderHeader` (label presence + stale-warning class), plus DOM-grep
checks that observers.js still tracks `_fetchedAt` and bypasses the
cache on manual refresh.
## TDD
Red commit asserts `ObserversSummary` doesn't exist / no `_fetchedAt`
tracking / no `obs-updated-stale` CSS → fails. Green commit adds the
implementation → passes.
## What this PR does NOT touch
- **Observer health thresholds** — owned by #1552, untouched here.
- **`healthStatus()` per-row classification** — untouched. The same
function still gates per-row colors AND aggregate counts; the fix is
about freshness visibility, not classification logic.
- **No new server endpoint** — Option 1 deferred. Will file a follow-up
if anyone wants that tracked.
---------
Co-authored-by: openclaw-bot <bot@openclaw.local>
Co-authored-by: mc-bot <bot@meshcore.local>
# fix(ingestor): write resolved_path on new observations (full restore —
closes#1547 + #1560)
Fixes#1547. Closes#1560.
## Root cause
PR #1289 (the "ingestor owns the neighbor graph; server is read-only"
refactor, ~2026-05-21) moved the neighbor graph + schema writes to the
ingestor, and as a side-effect removed the server-side writer that
populated `observations.resolved_path` AND the context-aware
`pm.resolveWithContext` that disambiguated 1-byte prefix collisions.
Result: every observation inserted after the deploy has `resolved_path =
NULL` (3.1M/6.3M NULL on staging; 100% NULL on fresh deploys; symptom on
Cascadia: hops fail to resolve because the small-mesh client-side
fallback breaks on prefix collisions).
## Full restore
This PR resolves both single-byte and multi-byte prefix paths.
Single-byte disambiguation uses NeighborGraph adjacency and ADVERT
`from_pubkey` anchoring, ported from pre-#1289 `pm.resolveWithContext`
logic (last good at cmd/server/store.go @ commit 450236d5) and the #1144
/ #1352 fixes.
New file `cmd/ingestor/path_resolver.go`:
- `NeighborGraph` + `neighborGraphHolder` — in-memory adjacency
snapshot, atomic-published.
- `loadNeighborGraph(db)` — one-shot SELECT from `neighbor_edges`.
- `resolveHopWithContext(hop, anchor, graph, idx, exclude) *string` —
single-hop, tier-1 disambiguator.
- `resolvePathWithContext(hops, fromPubkey, graph, idx) []*string` —
walks the path, anchoring hop 0 on `from_pubkey` (ADVERTs) and each
subsequent hop on the previous resolved hop, excluding already-resolved
pubkeys.
- `Store.RefreshNeighborGraph()` — called on warm-up and every 60s tick
in the neighbor-edges builder alongside `RefreshPrefixIndex`.
Existing file `cmd/ingestor/resolved_path.go` (PR #1547 base) is
untouched: `resolvePath` + `marshalResolvedPath` + the all-nil →
empty-string clobber-guard contract are preserved verbatim.
`cmd/ingestor/db.go` — `InsertTransmission` now calls
`resolvePathWithContext` instead of the naive `resolvePath`.
## Algorithm (per hop)
1. Look up candidate pubkeys by prefix-match (existing `prefixIndex`).
2. `len==0 → nil`; `len==1 → that pubkey`.
3. `len>1` → filter by `NeighborGraph` adjacency to the anchor. Anchor
is `from_pubkey` for hop 0 on ADVERTs, the previous resolved hop
otherwise. Exactly 1 surviving candidate → use it; else nil.
4. Previously resolved hops (and the originator) are excluded from
downstream candidate pools — a packet does not revisit a node.
Tier-2/3/4 from pre-#1289 (geo proximity, GPS preference,
observation-count fallback) are intentionally NOT ported — those were
noisy in practice and belong in a separate enhancement, not in this
regression restore.
## Out of scope
- The ~3.1M existing NULL rows from the regression window. Filed as a
follow-up backfill task — too risky to bundle here (touches a 6M-row
table).
- The dead-flag bug #1546 — separate concern.
## TDD red → green
- Red commit `80b0f476` — adds five new context-resolver tests; stub
`resolvePathWithContext` falls back to naive `resolvePath`. CI run
26946935615 → **failure** with assertion errors on the three collision
tests (`TestResolveHopWithContext_OneByteCollision_AdjacencyResolves`,
`TestResolvePathWithContext_TwoHopChainAnchoredOnFromNode`,
`TestResolvePathWithContext_AdvertAnchoring`); the two regression tests
(multi-byte still works + all-nil contract) stayed green.
- Green commit `7b4950ce` — real algorithm + InsertTransmission wiring +
RefreshNeighborGraph in the builder tick. All five new tests pass;
original four `resolved_path` tests stay green.
## Verification
- `go test -race ./cmd/ingestor/...` for the 11 affected tests — pass.
- `bash ~/.openclaw/skills/pr-preflight/scripts/run-all.sh
origin/master` — exit 0 (all gates clean).
- PII grep on body + diff: clean.
Tested with: existing `TestInsertTransmissionWritesResolvedPath` +
`TestInsertTransmissionDoesNotClobberResolvedPathOnAllNil` (PR #1547
base) plus the new collision-resolution suite:
- `TestResolveHopWithContext_OneByteCollision_AdjacencyResolves` —
3-of-5 nodes share `0x5c`, chain A↔B↔C↔D↔E; anchored on A, hop `5c` → B.
- `TestResolvePathWithContext_TwoHopChainAnchoredOnFromNode` — path
`[5c, 5c]` from_node A → `[B, C]`.
- `TestResolveHopWithContext_NoAdjacencyContext_ReturnsNil` — 3
ambiguous candidates, no anchor / non-adjacent anchor → nil.
- `TestResolvePathWithContext_AdvertAnchoring` — ADVERT,
`from_pubkey=A`, path `[5c]` → only-adjacent neighbor B.
- `TestResolvePathWithContext_RegressionMultiByteStillWorks` —
unique-prefix path with no graph context still resolves.
- `TestResolvePathWithContext_AllNilContractPreserved` — unresolvable
path → `marshalResolvedPath==""` (clobber-guard from PR #1548
untouched).
## Browser-validated
N/A — backend-only change. Frontend already handles populated
`resolved_path` via `getResolvedPath` in `cmd/server/db.go` and
`public/packets.js`.
## Round-1 fixes addressed
- **MUST-FIX #1 (data-loss clobber on all-nil resolution):** when every
hop fails to resolve, `marshalResolvedPath` returns `""` instead of
`"[null,null,...]"`, so `nilIfEmpty` → SQL NULL and the
`COALESCE(excluded.resolved_path, resolved_path)` UPSERT preserves any
previously stored good value on re-ingest. Regression test asserts:
insert a transmission, observe `resolved_path` populated, wipe the
prefix index, re-ingest the same packet, assert the existing
`resolved_path` is unchanged.
---------
Co-authored-by: corescope-bot <bot@corescope>
Co-authored-by: openclaw-bot <bot@openclaw>
Co-authored-by: openclaw-bot <bot@openclaw.local>
List of changes too long to describe, so I'll hit high level.
- Config now supports the json map tiles that were suggested by
@Kpa-clawbot.
- Leaflet map layer button appears in the top right of live.js and
map.js (because all the work was already done on live.js... Added bonus)
- Allows users to enter creds for OSM and Stamen to get enterprise
related perks, in the config file
- Added a default light map under customizer. Still suggest removing
them all together and relying on the config
- You can enable OSM and Stamen in the config without a license, but at
your own risk!!!
- Config comment explains where to register and the providers for osm,
as well as the general limits per X interval
- Updated tests (28) to address the changes made to the maps
### TDD Exemption
**Reason**: Net-new UI surfaces (per `AGENTS.md`)
This PR introduces a net-new UI surface (the multi-provider map tile
selector). Under the `AGENTS.md` exemption for net-new UI surfaces, the
absence of an initial failing (red) commit is permitted, as the UI was
built first. However, the underlying public APIs are fully covered.
The following tests serve as the first assertions for these new APIs:
- `window.MC_createLayerControl`: Asserted in `MC_createLayerControl
handles Auto mode and explicit layers correctly`
- `window.MC_setDarkTileProvider` & `window.MC_getDarkTileProvider`:
Asserted in `MC_setDarkTileProvider persists to localStorage...`
- `window.MC_setLightTileProvider` & `window.MC_getLightTileProvider`:
Asserted in `MC_setLightTileProvider persists to localStorage...`
- `window.MC_initTileRegistry`: Asserted in `MC_initTileRegistry(true)
dispatches mc-tile-provider-changed`
- `applyTileFilter`: Asserted in `applyTileFilter sets invert CSS for
inverted dark provider...`
- Cross-tab synchronization: Asserted in `Cross-tab storage event
re-dispatches mc-tile-provider-changed`
Closes#1561. Follow-up to #1551.
## Why
#1551 added `Cache-Control: no-store` to all `/api/*` responses. That's
sufficient for CDNs that honour origin headers (Varnish, nginx). It is
**not** sufficient for Cloudflare zones where Cache Rules / Page Rules
override origin Cache-Control.
Field evidence from the meshat.se diagnosis (2026-06-04): observers
behind Cloudflare were returning `cf-cache-status: HIT` with `age` up to
~6 hours despite the origin emitting `no-store`. The CDN was caching per
zone policy and ignoring the upstream directive — exactly the failure
mode #1551 cannot reach. The application has no way to inject CDN rules;
the only durable fix is operator-side.
This PR makes that operator step discoverable and verifiable.
## What
### Server-side detection (log-only)
`cmd/server/cdn_detection.go` adds a middleware wired into the `/api/*`
chain after `noStoreAPIMiddleware`. On the **first** request bearing any
CDN-typical header (`CF-Connecting-IP`, `CF-Ray`, `X-Forwarded-For`,
`X-Real-IP`, `Fastly-Client-IP`, `True-Client-IP`) it logs:
```
[security] WARNING: detected request via CDN (CF-Ray header present).
Ensure /api/* is bypassed in your CDN config — see docs/deployment-behind-cdn.md.
Cached API responses cause observer-flap and incorrect dashboards.
```
`sync.Once` guarantees the warning fires at most once per process boot.
The middleware never blocks, never modifies the response, never adds
headers. Detection is observational only — operators who run behind a
CDN without bypass have a real bug; the warning is appropriate.
### Operator documentation
`docs/deployment.md` gains a new **"Behind a CDN (Cloudflare, Fastly)"**
section covering:
1. Curl verification command + healthy vs unhealthy output examples
2. Cloudflare Cache Rule creation (URI Path starts-with `/api/` → Bypass
cache)
3. Legacy Page Rules equivalent
4. Fastly note
5. Re-verification
6. Meaning of the startup log warning
7. Why we can't fix this server-side
`docs/deployment-behind-cdn.md` is the canonical path the log message
references — it's a short TL;DR that links back to the full section.
### Healthcheck script
`scripts/check-cdn-bypass.sh` — POSIX sh, no dependencies beyond curl +
grep + awk. Operators run:
```sh
scripts/check-cdn-bypass.sh https://your-domain.example.com
```
Exits `0` with `OK: no CDN caching detected ...` or `1` with a precise
diagnostic naming the offending header (`cf-cache-status: HIT` or stale
`age`).
## TDD
- **Red commit `e90ccaba`** (`test(security): RED ...`) —
`cmd/server/cdn_detection_test.go` (4 Go tests + 6 subtests for each
header) and `scripts/test-check-cdn-bypass.sh` (3 shell harness cases).
Middleware stub returns `next` unchanged so tests compile and fail on
assertions, not build errors.
- **Green commit `5e6a60b5`** (`feat(security): GREEN ...`) — real
middleware, wiring in `routes.go`, healthcheck script, doc.
## Deliverables
| File | Status | Purpose |
|------|--------|---------|
| `cmd/server/cdn_detection.go` | new | middleware + sync.Once warning |
| `cmd/server/cdn_detection_test.go` | new | 4 Go tests (1 stand-alone +
1 silence + 1 once + 1 table-driven over 6 headers) |
| `cmd/server/routes.go` | modified | `r.Use(cdnDetectionMiddleware)`
after no-store |
| `docs/deployment.md` | modified | TOC entry + "Behind a CDN" section |
| `docs/deployment-behind-cdn.md` | new | canonical path referenced by
log message + script output |
| `scripts/check-cdn-bypass.sh` | new | operator-runnable healthcheck |
| `scripts/test-check-cdn-bypass.sh` | new | shell harness with fake
curl |
## What this PR explicitly does NOT do
- Does not block requests based on CDN detection (log-only).
- Does not enforce CDN bypass (impossible — operator-controlled).
- Does not spoof, strip or modify CDN headers.
- Does not add CSP / HSTS / other security headers (out of scope).
- Warning is not configurable — operators behind a CDN without bypass
have a real bug, surfacing it is correct.
## Verification
- `go test ./...` in `cmd/server/` — full suite green.
- `sh scripts/test-check-cdn-bypass.sh` — 3/3 pass.
- Preflight checklist — all 11 gates clean (PII, branch scope, red
commit, CSS vars, CSS self-fallback, LIKE-on-JSON, sync migration,
async-migration annotation, XSS sinks, img/SVG ratio, themed-img/SVG,
fixture coverage).
---------
Co-authored-by: openclaw-bot <bot@openclaw.local>
Co-authored-by: clawbot <bot@clawbot.invalid>
Kpa-clawbot