Summary

This PR hardens the Microsoft Graph webhook listener so externally reachable notification handling fails closed unless the receiver has a configured Graph clientState shared secret.

• Requires a non-empty client_state before the msgraph_webhook listener starts accepting notification POSTs.
• Changes the request-path verifier to reject notifications if the adapter is ever instantiated without an expected clientState.
• Changes the default listener host from all interfaces to loopback and documents when an operator should intentionally bind wider.
• Adds focused regression tests for the startup guard, POST rejection path, and loopback default.

Security issues covered

Before this PR

• _verify_client_state() returned True when no expected client_state was configured.
• MSGraphWebhookAdapter.connect() could start the listener without a notification shared secret.
• The default bind address was 0.0.0.0.
• The docs warned not to run without client_state, but the code still allowed that insecure configuration.
• Tests covered valid/invalid clientState comparisons but did not lock in fail-closed behavior for a missing expected secret.

After this PR

• connect() validates the security configuration before registering and starting the HTTP listener.
• Missing client_state now raises at startup instead of leaving a public POST endpoint in an unauthenticated mode.
• _verify_client_state() returns False if no expected secret exists, preserving fail-closed behavior if the adapter is constructed directly in tests or future code paths.
• The default host is 127.0.0.1, keeping the listener local unless an operator explicitly chooses a wider bind address.
• Regression tests cover the loopback default, missing-secret POST rejection, and missing-secret startup failure.

Explicit operator choice

Secure default behavior:

platforms:
  msgraph_webhook:
    enabled: true
    extra:
      client_state: "<strong random shared secret>"
      host: "127.0.0.1"

Intentional public-bind behavior:

platforms:
  msgraph_webhook:
    enabled: true
    extra:
      client_state: "<strong random shared secret>"
      host: "0.0.0.0"

The listener can still be exposed through a reverse proxy, tunnel, or explicit public bind when the operator chooses that deployment model. The important change is that the webhook receiver no longer starts without the Graph clientState secret that authenticates notification POSTs.

Why this matters

Microsoft Graph webhooks are public HTTPS callbacks. clientState is Microsoft's documented shared-secret mechanism for letting a receiver distinguish legitimate Graph notifications from arbitrary internet POSTs. Accepting notifications without that secret turns the endpoint into an unauthenticated inbound event surface.

The impact is integrity-focused: a forged notification can be accepted and scheduled as if it came from Graph. This PR does not claim code execution or data disclosure.

Attack flow

Unauthenticated internet POST
    -> Microsoft Graph webhook listener without configured client_state
        -> clientState verification returns true because no expected secret exists
            -> Hermes accepts and schedules the notification as an internal event

Affected code

Root cause

Missing fail-closed clientState requirement:

• The verifier treated an absent expected secret as an allow-all state.
• Startup did not enforce the same authentication requirement that the docs recommended.

Broad default listener bind address:

• The listener defaulted to all interfaces even though Graph webhook deployments commonly sit behind a public HTTPS proxy or tunnel.
• Operators had to opt out of broad binding instead of opting into it intentionally.

CVSS assessment

Rationale:

• The webhook endpoint is network-reachable in deployments that expose it for Microsoft Graph callbacks.
• Attack complexity is low when the listener is exposed without client_state.
• The demonstrated impact is integrity of Graph-derived event processing, not direct code execution or confidentiality loss.

Safe reproduction steps

1. Missing clientState fail-closed behavior

1. Configure the msgraph_webhook listener without client_state.
2. Send a well-formed notification POST to the webhook path with no shared-secret match possible.
3. Observe that pre-patch verification accepts the request because the missing expected secret makes _verify_client_state() return True.
4. Apply this PR and repeat: startup fails closed when client_state is absent, and the POST verifier also rejects if the adapter is ever instantiated without one.

2. Listener default bind address

1. Instantiate the adapter without an explicit host override.
2. Observe that pre-patch the default host is 0.0.0.0.
3. Apply this PR and observe that the default host is 127.0.0.1 unless the operator explicitly configures a wider bind address.

Expected vulnerable behavior

Before this PR, a deployment that enabled the Graph webhook listener without a client_state could accept arbitrary well-formed notification POSTs that matched the configured resource allowlist. The listener also defaulted to all interfaces, which made direct exposure easier when operators did not override the host.

After this PR, that missing-secret configuration is rejected at startup, request-path verification fails closed, and the listener defaults to loopback.

Changes in this PR

• Adds _validate_security_config() and calls it from MSGraphWebhookAdapter.connect() before the HTTP listener starts.
• Changes _verify_client_state() to return False when no expected secret is configured.
• Changes DEFAULT_HOST from 0.0.0.0 to 127.0.0.1.
• Adds regression tests for the loopback default, missing-secret POST rejection, and missing-secret startup failure.
• Updates the Microsoft Graph webhook docs to mark client_state as required and describe the loopback default / explicit public-bind choice.
• Stabilizes one CI-sensitive MCP cleanup test assertion so full xdist runs assert the intended grace-period behavior without depending on a process-wide sleep() mock seeing exactly one call.

Files changed

Maintainer impact

• Operators already following the documented quick start with MSGRAPH_WEBHOOK_CLIENT_STATE / extra.client_state are unaffected.
• Deployments that enabled the listener without a secret now fail at startup instead of accepting unauthenticated notifications.
• Deployments that intentionally bind the listener to all interfaces can still set host: "0.0.0.0" explicitly.
• The patch is limited to the Microsoft Graph webhook adapter, its docs, focused tests, and one CI-stability assertion needed for the PR's test run.

Fix rationale

Requiring client_state at startup is the right boundary because it prevents an externally reachable webhook receiver from entering an unauthenticated notification mode. Keeping the same fail-closed check in _verify_client_state() provides defense in depth if future code constructs the adapter directly or bypasses connect().

Changing the default host to loopback makes accidental direct exposure less likely while preserving an explicit operator-controlled path for deployments that intentionally bind publicly or run behind network controls.

Type of change

• Security fix
• Tests
• Documentation update
• Refactor with no behavior change

Test plan

• Focused Microsoft Graph webhook regression tests.
• Ruff on the touched gateway/test files.
• Python compile check for the touched gateway implementation.

Executed with:

python -m pytest tests/gateway/test_msgraph_webhook.py -q
python -m ruff check gateway/platforms/msgraph_webhook.py tests/gateway/test_msgraph_webhook.py
python -m py_compile gateway/platforms/msgraph_webhook.py

Results:

• 23 passed
• ruff: All checks passed!
• py_compile: passed

Remote CI note:

• Most GitHub checks are passing on the current head.
• The test check is currently failing and still needs separate CI triage; the PR-body update does not claim full remote CI is green.

Disclosure notes

• Claims are bounded to the Microsoft Graph webhook listener and notification authentication path.
• This PR does not claim direct code execution, data disclosure, or bypass of Microsoft Graph itself.
• No real Graph tenant IDs, webhook URLs, secrets, or production payloads are included.
• Public PR text intentionally omits usage accounting, local research-note paths, and automation telemetry.