feat(hosting): install provenance + a first-run hardening guide gated on it (#2380)

[obasilakis]

Summary

Records how an instance was installed, and shows a first-run HTTPS/VPN hardening guide on marketplace installs and nowhere else.

A marketplace droplet is the one install where Trinity knows at boot that it is on a public IPv4 with no domain, with zero network configuration, and an operator who has read no deployment docs.

The obvious predicate is unusable, and that is the whole design. Measured across all 16 managed instances: every one serves plain HTTP with no DOMAIN, no HTTPS_ENABLED, on a 100.x Tailscale CGNAT address — structurally identical to an unhardened droplet, and already correct, because HTTP over a WireGuard tunnel is encrypted transport (HOST-010). A "no TLS configured → warn" rule fires permanently on every paying client. No environmental signal separates the two cases. The install channel does, and it is knowable only at provisioning time.

Three properties that are security, not hygiene

• Write-once. Provenance is a fact about an installation event. If a later .env edit could rewrite it, it would answer "what does this box currently claim" instead, and the marketplace gate would be self-assertable by anyone who can edit a file. Enforced at the PRIMARY KEY on both backends (INSERT OR IGNORE / ON CONFLICT DO NOTHING), not by the SELECT before it — that is a separate statement, i.e. a check-then-act.
• No env fallback on read. get_install_source reads the row only. Without this, write-once is decorative: an unrecorded install could be talked into a marketplace verdict by exporting the variable.
• Blocked on PUT and DELETE, and refused at the db sink. The DELETE block is not symmetry — because the recorder is write-once, a delete is precisely the move that unlocks a rewrite. The sink guard follows db/settings.py's own stated rule (boundary and sink, since the catch-all can write any key — the door found open by feat(capacity): admin-configurable system-wide ceiling + agent-settings UI for max_parallel_tasks #506, Make proactive channel-message rate limits configurable (Slack/Telegram/DM guardrails) #1609, ent#12, bug: retention prunes have no blast-radius guard — a mistyped window deletes most of a table within 5 minutes #1644, ent#14, ent#346 in turn).

An unrecognised marker records nothing — not even unknown, which would combine with write-once to freeze a typo permanently. An absent row already reads unknown and lets a corrected marker land next boot.

Honest state by construction

Nothing probes a socket or reads a certificate — TLS terminates outside the backend, so no in-process check can. install_tls_posture is pure string parsing of the URL the instance advertises, resolved through the canonical get_public_chat_url() so it cannot disagree with public links and webhook registration about what this instance is called.

The card says "advertises", never "secure"; https-ip reads as working-but-upgradeable rather than broken (LE IP certs went GA 2026-01-15, DO's own 1-Click rules ship Caddy with them); and it states plainly that Trinity issues no certificate itself — nothing in the tree reads public_chat_url and reconfigures a proxy.

Review found four defects in the first cut, all fixed here

1. The https-ip copy asserted "a real, browser-trusted Let's Encrypt certificate … works today" on the evidence that a string starts with https:// — a direct AC violation, and the spec required the offending words. Copy rewritten; the honesty guard widened from grepping secure|verified|validated to rejecting connection-property claims generally, with a regression test that feeds it the old sentence and requires ≥4 hits.
2. The domain path promised "a normal 90-day certificate then replaces the short-lived IP one". Verified false — public_chat_url is a display/webhook-base setting. Now attributes the effect to whatever terminates TLS.
3. The card rendered for non-admins, whose only action dead-ends (general is adminOnly, so the button lands them on the default tab) and whose copy discloses the box's network posture. Admin-gated, matching AdminEmailNudge.vue.
4. It did not retire in-session: savePublicUrl never force-refreshed the flags, so the card survived the action it asked for until a hard reload.

Also: posture resolution diverged from the canonical URL resolver; write-once rested on a check-then-act; config imports sat outside the fail-safe guards; and two doc claims of mine overstated (the parity test is prod↔hosted only, and retirement is server state, not verified fact — an admin can type any domain and suppress it, which is accepted and now written down rather than implied otherwise).

Scope note

Nothing in the OSS tree writes the marker — #2281's Packer snapshot does. Until it lands, provenance reads unknown everywhere and the guide renders nowhere. That is PROV-004's contract working, and it is what makes shipping this half first safe.

Test plan

• pytest tests/unit/test_2380_install_provenance.py — 118 passed. Mutation-tested: removing write-once, recording unknown on a bogus marker, reintroducing the env fallback, and dropping either router guard are each caught.
• pytest tests/unit/test_2217_canary_status.py test_2280_hosted_compose_parity.py — 147 passed with the above
• Broader sweep (-k "settings or database or seed or version or ent435 …") — 754 passed; the single failure (test_736_a2a_outbound_properties) reproduces identically on clean dev and is environmental (local 3.11 vs the 3.13 image pin)
• npm run test:unit — 1528 passed; npm run build and npm run check:tokens clean; new component contributes zero raw colors
• Manual: set TRINITY_INSTALL_SOURCE=do-marketplace, boot, confirm the row records once, the card renders for an admin only, and a second boot with a different marker leaves it unchanged

Fixes #2380

🤖 Generated with Claude Code

[vybe]

Unblock status, @obasilakis:

CodeQL — both alerts were js/incomplete-multi-character-sanitization in src/frontend/tests/unit/hardeningGuide.spec.js (test-only). Dismissed as used in tests; the check should go green on the next analysis of this PR.

regression diff — this one is real and needs a fix. 4 new failures under HEAD that don't fail under BASE in any seed:

• test_187_jwt_revocation::test_minted_token_carries_jti
• test_voice_auth.TestVoiceWebSocketAuth::test_admin_bypasses_ownership
• test_voice_auth.TestVoiceWebSocketAuth::test_other_user_rejected_4003
• test_voice_auth.TestVoiceWebSocketAuth::test_owner_passes_auth_gate

The failure counts differ per head seed (6/3/2 vs base's 2/2/2), so this looks order-dependent — likely one of the PR's new tests leaking state (settings/env/module) into the JWT + voice-auth suites rather than a straight assertion break. Worth running the failing tests locally right after your new test modules to reproduce.

[obasilakis]

Fixed in 412256d.

Root cause. TestMarkerNormalisation called importlib.reload(config). Reload mutates the shared module object in place, and config.py mints a random SECRET_KEY at import whenever the env var is unset — which it is under the unit suite. Modules that bound from config import SECRET_KEY at their own import kept the old value while anything reading config.SECRET_KEY per request got the new one, so a JWT signed on one side failed verification on the other. That is exactly the #1895 divergence, and the pytest_collectstart hook written for it structurally cannot catch this shape: it restores sys.modules["config"] to the same object a reload has already mutated.

Reproduced deterministically before the fix, which also explains the varying counts:

pytest tests/unit/test_2380_install_provenance.py \
       tests/unit/test_187_jwt_revocation.py \
       tests/unit/test_voice_auth.py -p no:randomly
→ 4 failed  (your four, exactly)

Fix. The intent behind the reload was right — the marker fixture rebinds cfg.TRINITY_INSTALL_SOURCE directly and so proves nothing about the real boot path — so that is kept and only the mechanism changes: config.py is now executed under a throwaway module name never registered in sys.modules, running the identical module-level statement with none of the reach. Pinning SECRET_KEY across the reload, or snapshot/restore of the module dict, would both have worked; each leaves a cleanup step that can be forgotten and would need revisiting the day config grows another import-time-derived value. Isolation has nothing to restore. Same command now: 143 passed.

Verification. Full unit suite with the new module forced to run first (the ordering most likely to expose leakage from it), against the branch parent as baseline:

	failures
base 13a3de8c^	23
head + new module first	23

diff of the two FAILED sets is empty — identical, zero new failures. The 23 are pre-existing IPv6-mapped-address failures local to this machine (test_736_a2a_outbound_edges, test_ent14_registry_url_ssrf, test_mcp_validator::TestCgnatSsrfGuard, …), red on both sides and untouched by this branch.

CodeQL — thanks, and confirmed independently: the replace() calls are only in hardeningGuide.spec.js (comment-stripping so the spec can assert on prose). hardeningGuide.js and HardeningGuide.vue contain no replace() and no sanitization, so there is no production twin of the flagged pattern.

[vybe]

Validated via /validate-pr: settings-row-only (no schema change on either track), write-once enforced by PK, both catch-all routes 422 the key after the admin gate, TRINITY_INSTALL_SOURCE wired into all three compose files + .env.example (hosted parity test green), 28/28 checks green incl. six-seed pytest + regression diff + frontend-e2e, CodeQL alerts test-only. Locally: 147 + 525 backend tests and 31 vitest pass on the head. Approving.