fix(dev): rename dev seed to .vagent and target /api/v1/agent (VA-66) #73

Merged

nrupard merged 1 commit from fix/VA-66-dev-vagent-rename-and-path into main

2026-06-26 16:23:41 +02:00

nrupard commented

2026-06-26 16:04:58 +02:00

Owner

What

Fixes the broken dev .vagent tooling and points it at the real agent control path, plus documents cert-pin under TLS offload (parent epic VS-54).

Changes

Rename run/vervain-agent.msh{,.template} -> run/vervain-agent.vagent{,.template}. The justfile already referenced run/vervain-agent.vagent.template, but the tracked files were the pre-VS-42 .msh names, so just ensure-settings / ensure-settings-host hit the missing-template branch and exited 1. Completes the VS-42 .msh -> .vagent rename.
Path /agent.ashx -> /api/v1/agent in the template, the dev seed, and the justfile's echoed render line, matching the server's wire_paths::AGENT_WS_PATH.
gitignore the agent's generated run/ artifacts (*.vss, install.secret, *.vagent.bak).
README documents the offload cert-pin behavior (below).

Dev target host

VERVAIN_SERVER_HOST defaults to the dev API server dev-vervain-server-app-dev; host mode forces 127.0.0.1. Neither is a frontend host.

Cert-pin under TLS offload

The handshake has two independent pins, so it stays correct when a proxy terminates TLS:

The ServerID SPKI pin is the server's signing identity, independent of the TLS cert.
The leaf-hash signature binds the proven identity to the exact cert the agent saw. Under offload the agent sees the proxy cert, and the server signs that same hash because VERVAIN_CERT_URL (VS-27) makes it fetch + advertise the proxy cert. Without it the handshake fails closed with ServerCertMismatch.

The live offload end-to-end run (agent against a Traefik-terminated dev endpoint) is an operational verification step; the pin logic and configuration are confirmed in code and documented.

Verification

just ensure-settings -> ws://dev-vervain-server-app-dev:4302/api/v1/agent (exit 0); just ensure-settings-host -> wss://127.0.0.1:.../api/v1/agent (exit 0). Pre-commit (fmt + clippy + check + test) green.

Acceptance criteria

just ensure-settings / ensure-settings-host succeed from a clean checkout.
Rendered .vagent ServerURL/GroupServer is on /api/v1/agent at the dev API host.
No run/*.msh* remain; only run/*.vagent*.
Cert-pin under offload documented.

## What Fixes the broken dev `.vagent` tooling and points it at the real agent control path, plus documents cert-pin under TLS offload (parent epic VS-54). ## Changes - **Rename `run/vervain-agent.msh{,.template}` -> `run/vervain-agent.vagent{,.template}`.** The justfile already referenced `run/vervain-agent.vagent.template`, but the tracked files were the pre-VS-42 `.msh` names, so `just ensure-settings` / `ensure-settings-host` hit the missing-template branch and exited 1. Completes the VS-42 `.msh -> .vagent` rename. - **Path `/agent.ashx` -> `/api/v1/agent`** in the template, the dev seed, and the justfile's echoed render line, matching the server's `wire_paths::AGENT_WS_PATH`. - **gitignore** the agent's generated `run/` artifacts (`*.vss`, `install.secret`, `*.vagent.bak`). - **README** documents the offload cert-pin behavior (below). ## Dev target host `VERVAIN_SERVER_HOST` defaults to the dev API server `dev-vervain-server-app-dev`; host mode forces `127.0.0.1`. Neither is a frontend host. ## Cert-pin under TLS offload The handshake has two independent pins, so it stays correct when a proxy terminates TLS: - The **ServerID SPKI** pin is the server's signing identity, independent of the TLS cert. - The **leaf-hash signature** binds the proven identity to the exact cert the agent saw. Under offload the agent sees the proxy cert, and the server signs that same hash because `VERVAIN_CERT_URL` (VS-27) makes it fetch + advertise the proxy cert. Without it the handshake fails closed with `ServerCertMismatch`. The live offload end-to-end run (agent against a Traefik-terminated dev endpoint) is an operational verification step; the pin logic and configuration are confirmed in code and documented. ## Verification `just ensure-settings` -> `ws://dev-vervain-server-app-dev:4302/api/v1/agent` (exit 0); `just ensure-settings-host` -> `wss://127.0.0.1:.../api/v1/agent` (exit 0). Pre-commit (fmt + clippy + check + test) green. ## Acceptance criteria - `just ensure-settings` / `ensure-settings-host` succeed from a clean checkout. - Rendered `.vagent` `ServerURL`/`GroupServer` is on `/api/v1/agent` at the dev API host. - No `run/*.msh*` remain; only `run/*.vagent*`. - Cert-pin under offload documented.

nrupard added 1 commit

2026-06-26 16:04:59 +02:00

fix(dev): rename dev seed to .vagent and target /api/v1/agent

Check / fmt + clippy + tests (pull_request) Successful in 18m39s

Details

Create release / Create release from merged PR (pull_request) Has been skipped

Details

b6dd4db562

The justfile already referenced run/vervain-agent.vagent.template, but the tracked files were still the pre-VS-42 run/vervain-agent.msh and run/vervain-agent.msh.template, so just ensure-settings / ensure-settings-host hit the missing-template branch and exited 1. Rename both to .vagent / .vagent.template (completes the VS-42 .msh -> .vagent rename) so the render recipes succeed from a clean checkout.

Switch the rendered ServerURL path from the legacy MeshCentral /agent.ashx to the current wire path /api/v1/agent (server crates/vervain-web/src/wire_paths.rs), in the template, the dev seed, and the justfile's echoed render line, so the dev agent reproduces the real control path. The dev target host stays the dev API server (VERVAIN_SERVER_HOST default dev-vervain-server-app-dev; host mode forces 127.0.0.1), never a frontend host (parent VS-54).

gitignore the agent's generated run/ artifacts (the sealed .vss, install.secret, and rotated .vagent.bak) so a local run does not leave them staged. README documents that under TLS offload the cert-pin stays correct: the ServerID SPKI pin is independent of TLS, and the leaf-hash signature matches because the server advertises the terminating proxy's cert hash via VERVAIN_CERT_URL (VS-27); without it the handshake fails closed with ServerCertMismatch.

Verified: just ensure-settings renders ws://dev-vervain-server-app-dev:4302/api/v1/agent and ensure-settings-host renders wss://127.0.0.1:.../api/v1/agent, both exit 0.

#VA-66

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

nrupard scheduled this pull request to auto merge when all checks succeed

2026-06-26 16:17:09 +02:00