fix(webhooks): harden trigger response surface (#1177)

* fix(webhooks): harden trigger response surface

Bundles six audit findings on the incoming-webhooks trigger path. All
changes preserve the documented happy path: a CI caller signing the exact
request body with the webhook secret still receives 202 Accepted.

* Uniform 404 on every unauthenticated rejection (missing webhook,
  disabled webhook, non-paid tier, missing signature header, missing
  raw body, signature mismatch). The four-way response surface previously
  let an unauthenticated probe enumerate webhook ids and fingerprint the
  instance's licence tier; callers now see one shape for any failed auth.
* Fail closed when express.json()'s verify callback did not capture the
  raw request body. Previously the handler fell back to
  JSON.stringify(req.body), which compares the HMAC against a
  re-serialised payload that is not byte-equal to what the client signed.
* Pass the already-loaded webhook through to WebhookService.execute()
  instead of re-fetching by id. Closes the delete-during-execution race
  where an admin deletion between the trigger handler's load and the async
  dispatch silently dropped the execution row. The webhook_executions
  table has ON DELETE CASCADE, so recordExecution now wraps the insert in
  try/catch and logs a warning when the FK constraint trips because the
  parent webhook was deleted mid-flight.
* Redact bearer tokens, JWTs, URL credentials, and homedir paths from
  error strings before persisting to webhook_executions.error. The
  execution history is readable by any paid user via GET /webhooks/:id/
  history; redactSensitiveText gains three home-directory patterns
  (/home/<user>, /Users/<user>, <drive>:\Users\<user>) and now runs on
  every error stored from this path.
* Cap webhook name at 100 characters on both POST and PUT, rejecting
  non-string and oversized values with 400 before they reach the DB.
* Validate the body's action override against a typed allowlist
  (isWebhookAction type guard) on the trigger endpoint, returning 400
  before queueing execution. An unknown override no longer reaches
  recordExecution as a stored failure row.

Tests updated to pass db.getWebhook(id)! instead of the raw id to the new
execute() signature. Docs at docs/features/webhooks.mdx updated to reflect
the new uniform 404 response, the new 400-on-invalid-action behaviour, and
a rewritten troubleshooting accordion that walks operators through every
cause of the uniform 404.

* test(webhooks): cover trigger handler auth, race, and redaction paths

Adds 21 vitest cases for the public webhook trigger handler and the
WebhookService.execute / recordExecution pipeline, plus 3 cases for the
new homedir patterns in redactSensitiveText.

webhooks-trigger.test.ts covers, per audit finding:

* M1 + H3 uniform 404: id unknown, webhook disabled, non-paid tier,
  missing signature header, missing rawBody, sha1= prefix, malformed
  hex signature, sig mismatch. Each asserts identical 404 body so a
  future regression that re-introduces 401 / 403 / PAID_REQUIRED breaks
  one of the 8 tests.
* Happy path: 202 with configured action, valid action override,
  unknown action override returns 400 after auth succeeds (L2),
  non-string action override returns 400.
* L1 name cap: POST and PUT both reject names over 100 chars and
  non-string names; 100-char boundary still accepted; PUT allows
  partial updates that omit name.
* M5 race: deleting the parent webhook before recordExecution runs no
  longer crashes the async dispatch; the FK cascade is swallowed with
  a console.warn, and a happy-path test pins the recordExecution row.
* M6 redaction: stubs ComposeService.runCommand to throw errors
  containing a bearer token and a homedir path, then asserts the
  persisted webhook_executions.error has both scrubbed.

safe-log.test.ts gains three unit tests pinning the new homedir
patterns in redactSensitiveText (Linux, macOS, Windows). The existing
credentials test is untouched.

Tests use prototype spies on FileSystemService and ComposeService (both
hand out a fresh instance per nodeId), so per-test mocks do not leak.
beforeEach restores all mocks and reapplies the LicenseService 'paid'
spy. Closes audit finding H2 (zero trigger-path test coverage).

* docs(webhooks): sync openapi spec with new trigger response surface

Brings docs/openapi.yaml in line with the behaviour changes from the
trigger hardening commit. Mintlify auto-generates the per-endpoint
reference pages from this spec, so the spec drift would surface as
wrong response codes in the public API reference.

POST /api/webhooks and PUT /api/webhooks/🆔
  * name: maxLength 100 (matches MAX_WEBHOOK_NAME_LENGTH on the route).
  * action enum: add git-pull (pre-existing omission; the route has
    always accepted it).
  * node_id: documented as an integer property (pre-existing omission).

POST /api/webhooks/:id/trigger:
  * requestBody required: true (body is now mandatory; the H3
    fail-closed branch rejects a missing rawBody).
  * action override: enum restricted to the allowlist.
  * 401 and 403 responses removed.
  * 404 response: description rewritten to reflect uniform-404
    behaviour; the body is { error: "Webhook not found or signature
    invalid" } for every unauthenticated reject.
  * 400 response added for an authenticated request whose action
    override is not in the allowlist.

docs/features/webhooks.mdx

@@ -100,16 +100,15 @@ By default, the webhook executes the action configured at creation time. You can
 { "action": "restart" }
 ```
 
-Valid override values are: `deploy`, `restart`, `stop`, `start`, `pull`, `git-pull`. An unknown value causes the execution to fail and appear with an error in **Recent executions**.
+Valid override values are: `deploy`, `restart`, `stop`, `start`, `pull`, `git-pull`. An unknown value is rejected with `400 Bad Request` before execution is queued.
 
 ### Responses
 
 | Status | Body | Meaning |
 |--------|------|---------|
 | `202 Accepted` | `{ "message": "Webhook accepted", "action": "deploy" }` | Signature is valid; the action is now running asynchronously. A 202 means accepted, not finished. |
-| `401 Unauthorized` | `{ "error": "Missing X-Webhook-Signature header" }` | The request omitted the signature header. |
-| `401 Unauthorized` | `{ "error": "Invalid signature" }` | The provided signature did not match the expected HMAC. |
-| `404 Not Found` | `{ "error": "Webhook not found or disabled" }` | The webhook id is unknown or its enable toggle is off. |
+| `400 Bad Request` | `{ "error": "action must be one of: deploy, restart, stop, start, pull, git-pull" }` | The request authenticated successfully but the body's `action` override was not in the allowlist. |
+| `404 Not Found` | `{ "error": "Webhook not found or signature invalid" }` | The webhook id is unknown, the webhook is disabled, the signature header is missing, the request body was empty, or the signature did not match. Sencho returns the same response for every unauthenticated case so callers cannot probe ids or licence state. |
 
 ## CI/CD integration examples
 
@@ -166,19 +165,17 @@ Sencho retains the last 100 executions per webhook and surfaces the 20 most rece
     The page requires a **Skipper** or **Admiral** license. If you are on a paid tier but the node switcher in the top-left shows a remote node, switch to **Local** to reveal the page.
   </Accordion>
 
-  <Accordion title="My trigger returns '401 Invalid signature'.">
-    The signature must be computed over the **exact raw bytes** of the request body. Common causes:
+  <Accordion title="My trigger returns 404 'Webhook not found or signature invalid'.">
+    The trigger endpoint returns the same 404 for every unauthenticated case, so the response alone will not tell you which check failed. Work through this checklist:
 
-    - The CI step JSON-encodes the body before signing but sends a different body to curl (or vice versa). Sign the same string you send.
-    - The shell adds a trailing newline (use `echo -n` rather than `echo`).
-    - The header is missing the `sha256=` prefix; the full value is `sha256={hex}`.
+    - The id in the URL is wrong. Copy the trigger URL straight from the webhook card in **Settings → Alerts → Webhooks**.
+    - The webhook's enable toggle is off. Check the **On / Off** switch on the card.
+    - The request omitted the `X-Webhook-Signature` header. Confirm the full value, including the `sha256=` prefix; the header value is `sha256={hex}`.
+    - The request had no body. Send at least `{}` and sign that exact byte sequence.
+    - The signature was computed over different bytes from what the request carried. Sign the exact string you send. Common offenders: the CI step JSON-encodes the body before signing but pipes a different body to curl, or the shell adds a trailing newline (use `echo -n` rather than `echo`).
     - The webhook secret used to sign does not match the secret stored in Sencho. The secret is shown once at creation; if you lost it, delete the webhook and create a new one.
   </Accordion>
 
-  <Accordion title="My trigger returns '404 Webhook not found or disabled'.">
-    The id in the URL is wrong, or the webhook's enable toggle is off. Copy the trigger URL from the card and check the **On / Off** switch on the webhook in **Settings → Alerts → Webhooks**.
-  </Accordion>
-
   <Accordion title="The action returns 202 but the stack does not change.">
     A 202 means the action was accepted, not that it produced a visible change. **Pull & Update** is a no-op if the registry has no newer image for any service in the stack; **Start** is a no-op on an already-running stack. Check the stack's **Activity** sheet to confirm what actually ran, and the webhook's **Recent executions** for the action's status and duration.
   </Accordion>

docs/openapi.yaml

@@ -1447,6 +1447,7 @@ paths:
               properties:
                 name:
                   type: string
+                  maxLength: 100
                   example: GitHub Deploy Hook
                 stack_name:
                   type: string
@@ -1454,11 +1455,14 @@ paths:
                   example: my-app
                 action:
                   type: string
-                  enum: [deploy, restart, stop, start, pull]
-                  description: Action to execute when the webhook is triggered.
+                  enum: [deploy, restart, stop, start, pull, git-pull]
+                  description: Action to execute when the webhook is triggered. `git-pull` requires a Git source attached to the stack.
                 enabled:
                   type: boolean
                   default: true
+                node_id:
+                  type: integer
+                  description: Node the webhook executes against. Defaults to the request's resolved node or the default node.
       responses:
         "201":
           description: Webhook created. The `secret` field is the HMAC signing key — save it now.
@@ -1501,13 +1505,17 @@ paths:
               properties:
                 name:
                   type: string
+                  maxLength: 100
                 stack_name:
                   type: string
                 action:
                   type: string
-                  enum: [deploy, restart, stop, start, pull]
+                  enum: [deploy, restart, stop, start, pull, git-pull]
                 enabled:
                   type: boolean
+                node_id:
+                  type: integer
+                  description: Retarget the webhook to a different node.
       responses:
         "200":
           description: Webhook updated.
@@ -1577,15 +1585,20 @@ paths:
       summary: Trigger webhook
       description: |
         Externally triggers a webhook action. This endpoint is public but requires a valid
-        HMAC-SHA256 signature in the `X-Webhook-Signature` header.
+        HMAC-SHA256 signature in the `X-Webhook-Signature` header. Sign the exact raw bytes
+        of the request body; an empty body is rejected.
 
         Compute the signature as: `sha256=` + HMAC-SHA256(raw_request_body, webhook_secret).
+
+        Every unauthenticated rejection (unknown id, disabled webhook, non-paid licence,
+        missing or invalid signature, empty body) returns the same `404` response so callers
+        cannot enumerate webhook ids or fingerprint the instance's licence tier.
       security:
         - webhookSignature: []
       parameters:
         - $ref: "#/components/parameters/idPath"
       requestBody:
-        required: false
+        required: true
         content:
           application/json:
             schema:
@@ -1593,7 +1606,8 @@ paths:
               properties:
                 action:
                   type: string
-                  description: Override the default webhook action.
+                  enum: [deploy, restart, stop, start, pull, git-pull]
+                  description: Override the default webhook action. Must be one of the allowed actions.
       responses:
         "202":
           description: Webhook accepted and action queued.
@@ -1609,16 +1623,14 @@ paths:
                   action:
                     type: string
                     example: deploy
-        "401":
-          description: Missing or invalid signature.
+        "400":
+          description: Authentication succeeded but the body's `action` override was not in the allowlist.
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-        "403":
-          $ref: "#/components/responses/Forbidden"
         "404":
-          description: Webhook not found or disabled.
+          description: Authentication failed. The webhook is unknown, disabled, the licence is not paid, the signature header is missing, the body was empty, or the signature did not match. Sencho returns the same response for every unauthenticated case.
           content:
             application/json:
               schema: