Hello

mesh-ext-hello

A minimal external Mesh extension. It is the reference used to test installing, updating and permission changes of external extensions, and a template for third-party authors.

What it does

Endpoint	Purpose
GET /healthz	liveness, returns the running version
POST /mesh/install	receives extension_id, version, workspace_id, signing_secret, events and events_path from Mesh; the body carries no JWKS URL
POST /mesh/events	receives events; verifies X-Mesh-Signature = HMAC-SHA256 of {X-Mesh-Timestamp}.{body} (hex), rejects skew over 300 s
GET /mesh/ui/hello	sidebar.item screen: greets the user from the JWT, button sends mesh.toast
GET /mesh/ui/task	task.panel screen

UI requests carry a Mesh-issued JWT (Authorization: Bearer or ?token=), checked against the JWKS. Mesh does not send the JWKS URL on install, so set MESH_JWKS_URL on the service (see Configuration); without it UI requests are rejected.

Disclosures

• Permissions: tasks:read. Version 0.2.0 adds comments:write and 0.4.0 adds tasks:write (used to test the permission delta).
• Events: task.updated.
• UI slots: sidebar.item, task.panel.
• Data stored: the signing secret in HELLO_STATE_FILE (and a JWKS URL only if the install body carries one); the last 50 event types in memory only.

Network

Mesh calls this service at the URL set in workspace settings. The service makes exactly one kind of outbound request: it fetches the signing keys (JWKS) from the URL in MESH_JWKS_URL to verify the token of a UI request. It contacts no other host.

Accounts

None. The service has no accounts of its own and uses no external accounts or API keys. It only verifies the JWT that Mesh issues, against the Mesh JWKS.

Telemetry

None. Nothing is sent to the author or to any third party. The local log holds: the event type and delivery id of each incoming event, the workspace id on install, and one line per HTTP request of any kind (method and path, without the query string, so a ?token= JWT is never logged).

Configuration

Variable	Meaning
PORT	listen port, default 8080
HELLO_SIGNING_SECRET	optional; overrides the secret received on install
MESH_JWKS_URL	JWKS URL of the Mesh instance, required to verify UI tokens (not sent by Mesh on install; used if the install body includes jwks_url, the env value wins)
HELLO_JWT_AUDIENCE	expected aud, default ext-hello
MESH_ORIGIN	origin allowed to frame the UI
HELLO_STATE_FILE	where install data is kept
HELLO_DEBUG=1	enables GET /mesh/debug/events for acceptance checks

Development

python3 -m venv .venv && .venv/bin/pip install -r requirements-dev.txt
.venv/bin/pytest
.venv/bin/python scripts/validate_manifest.py

Releases

Tags X.Y.Z build git.entire.host:5050/entire-vc/mesh-ext-hello:X.Y.Z. Branch beta builds the beta tag.