feat(host/hooks): operator hooks — exec + webhooks on lifecycle events (M2a)

hooks.json (RFC §6): commands and webhooks fired on host lifecycle events,
managed over GET|PUT /api/v1/hooks (validated, applied immediately) and
dispatched fire-and-forget by a bus-subscriber runner — hooks observe,
never veto, and no operator code sits in any streaming path.

- exec: detached sh -c with the event JSON on stdin + flat PF_EVENT_* env
  (the PF_STREAM_* vocabulary's sibling), per-hook timeout (default 30 s)
  with process-group kill, off-thread reap, per-hook debounce, bounded
  concurrency (8 in flight, excess dropped loudly). Windows runs hooks in
  the interactive user session (temp-file JSON argument; console-mode dev
  hosts get env + stdin like Unix).
- webhook: POST the event JSON, TLS-verified, redirects never followed, no
  punktfunk credentials outbound; optional per-hook secret file yields
  X-Punktfunk-Signature: sha256=<hex HMAC> (fails closed if unreadable).
- filters: exact-match client/fingerprint/plane/app + the same kind
  patterns as the SSE ?kinds= filter (shared crate::events::kind_matches).
- hardening (RFC §9.1): hooks.json via the private-dir/secret-file
  helpers; a hook script path must be operator/root-owned and not
  group/world-writable or it is refused loudly (the sshd rule).
- env mirrors PUNKTFUNK_ON_CONNECT_CMD / PUNKTFUNK_ON_DISCONNECT_CMD for
  the zero-config cases, beside PUNKTFUNK_RECOVER_SESSION_CMD.

Live-verified on Linux: PUT config via API → library.changed fired a real
script (env + stdin observed) and an HMAC webhook (receiver-verified
signature); a chmod-777 script was refused. 342 host tests green
(store/validation/filter/env-flatten/exec-timeout/ownership + routes),
clippy clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

crates/punktfunk-host/src/mgmt/hooks.rs

@@ -0,0 +1,57 @@
+//! Hooks management endpoints (scripting-and-hooks RFC §6): read and replace the operator's
+//! `hooks.json` — validated on write, applied immediately (the runner reads the store per
+//! event, so no restart is needed).
+
+use super::shared::*;
+
+/// Get the hook configuration
+///
+/// The operator's `hooks.json`: commands and webhooks fired on host lifecycle events. Empty
+/// when unconfigured.
+#[utoipa::path(
+    get,
+    path = "/hooks",
+    tag = "hooks",
+    operation_id = "getHooks",
+    responses(
+        (status = OK, description = "The stored hook configuration", body = crate::hooks::HooksConfig),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn get_hooks() -> Json<crate::hooks::HooksConfig> {
+    Json(crate::hooks::store().get())
+}
+
+/// Replace the hook configuration
+///
+/// Validates and persists a full `hooks.json` document (this is a whole-document PUT, not a
+/// patch). Applies from the next event — no restart. Hook commands run as the host user
+/// (interactive user session on Windows): treat this configuration as operator-privileged.
+#[utoipa::path(
+    put,
+    path = "/hooks",
+    tag = "hooks",
+    operation_id = "setHooks",
+    request_body = crate::hooks::HooksConfig,
+    responses(
+        (status = OK, description = "Configuration stored; the new state", body = crate::hooks::HooksConfig),
+        (status = BAD_REQUEST, description = "Structurally invalid configuration", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+        (status = INTERNAL_SERVER_ERROR, description = "Configuration could not be persisted", body = ApiError),
+    )
+)]
+pub(crate) async fn set_hooks(ApiJson(cfg): ApiJson<crate::hooks::HooksConfig>) -> Response {
+    if let Err(e) = cfg.validate() {
+        return api_error(StatusCode::BAD_REQUEST, &e);
+    }
+    match crate::hooks::store().set(cfg) {
+        Ok(()) => {
+            tracing::info!("management API: hook configuration updated");
+            Json(crate::hooks::store().get()).into_response()
+        }
+        Err(e) => api_error(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            &format!("persist hooks.json: {e:#}"),
+        ),
+    }
+}