WebhookTrigger: provider-agnostic template verifier

[chubes4]

Closes #1179. Replaces the (closed, unmerged) #1186 rebuild.

Why this exists

#1186 shipped the template engine but leaked provider-specific knowledge back into DM core in three places:

1. A hardcoded 'sha256=hex' | 'hex' | 'base64' switch in the resolver.
2. GitHub-style defaults (X-Hub-Signature-256 / sha256=hex) used as silent fallbacks in the ability.
3. A provider-named allow-list for safe-header logging (stripe-signature, x-slack-signature, x-shopify-hmac-sha256, etc.).

The constraint was strict: no provider names anywhere in core, everything supported via flow config. #1186 violated that constraint. This PR is the rebuild that actually honors it.

What's different from #1186

• No auth_mode = hmac_sha256 anywhere. Replaced with the generic primitive hmac.
• No v1 shorthand CLI flags. --signature-header, --signature-format, --auth-mode=hmac_sha256, and the v1 fields they wrote (webhook_signature_header, webhook_signature_format, webhook_secret) are gone from the user-facing surface. Flows enable via --preset=<name> (filter-registered) or --config=@template.json (explicit template).
• No GitHub-style defaults. An HMAC flow without a resolved template cleanly 401s instead of silently behaving like a GitHub receiver.
• Pattern-based safe-headers deny-list (/secret|token|sig|hmac|signature|auth|password|bearer|api[-_]?key/i + hard blocks for authorization / cookie / proxy-authorization). Zero provider names in the logging code.
• Preset names never persist on the flow row. The preset expands to a full template at enable time; changing a preset registration later doesn't silently mutate already-configured flows.
• Single place in core that knows about the legacy v1 enum — WebhookAuthResolver::migrate_legacy(), called once on first read, which converts and then deletes the v1 fields. No other code path references legacy field names.

The architecture

Request ──▶ Trigger ──▶ Resolver ──▶ Verifier
                │
                └─▶ silent v1 migration on first read (once per flow, ever)

scheduling_config = [
    'webhook_enabled'   => true,
    'webhook_auth_mode' => 'bearer' | 'hmac',
    // bearer-only:
    'webhook_token'     => '...',
    // hmac-only — always a full template when present:
    'webhook_auth'      => [
        'mode'             => 'hmac',
        'algo'             => 'sha256',
        'signed_template'  => '{timestamp}.{body}',     // {body} {timestamp} {id} {url} {header:X} {param:X}
        'signature_source' => [ header|param, extract, encoding ],
        'timestamp_source' => [ header|param, extract, format ],   // optional → enables replay protection
        'id_source'        => [ header|param, extract ],           // optional
        'tolerance_seconds'=> 300,
        'max_body_bytes'   => 1048576,
    ],
    'webhook_secrets' => [ ['id' => 'current', 'value' => '...'], ... ],
]

Extract kinds: raw | prefix | kv_pairs | regex. Encodings: hex | base64 | base64url. Timestamp formats: unix | unix_ms | iso8601.

Extension points

• datamachine_webhook_auth_presets — third parties register provider shorthands. Core ships zero presets.
• datamachine_webhook_verifier_modes — third parties register non-HMAC modes (Ed25519, x509, JWT, mTLS). Core ships only hmac.

New CLI surface

# HMAC via preset (core ships zero presets)
wp datamachine flows webhook enable 42 --preset=<name> --generate-secret

# HMAC via explicit template config
wp datamachine flows webhook enable 42 --config=@template.json --secret=<value>

# Deep-merge overrides on top of a preset/config
wp datamachine flows webhook enable 42 --preset=<name> --overrides=@overrides.json --generate-secret

# Zero-downtime rotation
wp datamachine flows webhook rotate 42 --generate [--previous-ttl-seconds=N]
wp datamachine flows webhook forget 42 previous

# List filter-registered presets
wp datamachine flows webhook presets

Tests

homeboy test data-machine -- --filter='Webhook'
OK (82 tests, 170 assertions)

Full suite: 1195 passed, 37 pre-existing failures unchanged.

+58 new tests; zero new regressions.

• WebhookVerifierTest (29) — pure unit. Shape-named matrix (prefixed_hex / base64_header / raw_hex / kv_timestamped / separate_timestamp / id_timestamped / url_params) × (valid / tampered / wrong secret) + replay edges + multi-secret rotation + expiry + all error paths.
• WebhookAuthResolverTest (13) — v1→v2 migration including orphan-field cleanup + no-op cases + preset filter + deep-merge.
• WebhookTriggerTest (17) — end-to-end. Bearer regression, HMAC via preset + explicit template + overrides, no-template-returns-401 (not GitHub default), rotation grace window, forget invalidation, silent v1 migration through the REST handler, pattern-based safe-headers deny-list.
• WebhookSignatureVerifierTest (15) — kept as regression coverage for the deprecated v1 shim.

Lint

Clean for new/modified files. The only phpstan finding attributable to WebhookTriggerAbility is a shared FlowHelpers trait signal that predates this PR.

Backward compatibility — verified by test

test_v1_legacy_flow_migrates_silently_and_still_authenticates:

1. Writes a flow to the DB directly in the v1 shape.
2. Sends a valid v1-signed request.
3. Asserts the request authenticates.
4. Asserts the stored config is now in canonical v2 shape and the v1 fields are gone.

Bearer flows are untouched.

LOC

2,976 insertions, 779 deletions = net +2,197 LOC including tests and docs. The engine + resolver + result is ~790 LOC; the rest is abilities / CLI / tests / docs.

Out of scope (future issues)

• Dedicated {prefix}_webhook_secrets table with migration.
• Structured verification log table.
• Outbound (AgentPing) signing via the same grammar.
• Nonce-based replay storage beyond timestamp window.
• Concrete Ed25519 / x509 / JWT implementations for the mode registry.

[homeboy-ci]

Homeboy Results — data-machine

Audit

⚡ Scope: changed files only

✅ audit (changed files only)

• Alignment score: 0.818
• Outliers in current run: 42
• Drift increased: no
• Severity counts: info: 27, unknown: 42, warning: 177
• Top actionable findings:
  1. inc/Api/WebhookVerifier.php — missing_method — Missing method: register
  2. inc/Api/WebhookVerifier.php — missing_method — Missing method: register_routes
  3. inc/Api/WebhookVerifier.php — missing_registration — Missing registration: rest_api_init
  4. inc/Api/WebhookSignatureVerifier.php — missing_method — Missing method: register
  5. inc/Api/WebhookSignatureVerifier.php — missing_method — Missing method: register_routes
  6. inc/Api/WebhookSignatureVerifier.php — missing_registration — Missing registration: rest_api_init
  7. inc/Api/WebhookAuthResolver.php — missing_method — Missing method: register
  8. inc/Api/WebhookAuthResolver.php — missing_method — Missing method: register_routes
  9. inc/Api/WebhookAuthResolver.php — missing_registration — Missing registration: rest_api_init
  10. inc/Api/WebhookVerificationResult.php — missing_method — Missing method: register

Audit findings (10 shown)

1. **inc/Api/WebhookVerifier.php** — missing_method — Missing method: register
2. **inc/Api/WebhookVerifier.php** — missing_method — Missing method: register_routes
3. **inc/Api/WebhookVerifier.php** — missing_registration — Missing registration: rest_api_init
4. **inc/Api/WebhookSignatureVerifier.php** — missing_method — Missing method: register
5. **inc/Api/WebhookSignatureVerifier.php** — missing_method — Missing method: register_routes
6. **inc/Api/WebhookSignatureVerifier.php** — missing_registration — Missing registration: rest_api_init
7. **inc/Api/WebhookAuthResolver.php** — missing_method — Missing method: register
8. **inc/Api/WebhookAuthResolver.php** — missing_method — Missing method: register_routes
9. **inc/Api/WebhookAuthResolver.php** — missing_registration — Missing registration: rest_api_init
10. **inc/Api/WebhookVerificationResult.php** — missing_method — Missing method: register

Tooling versions

• Homeboy CLI: homeboy 0.89.1+d617b4d6
• Extension: wordpress from https://github.com/Extra-Chill/homeboy-extensions
• Extension revision: unknown
• Action: Extra-Chill/homeboy-action@v2

---

Homeboy Action v1