Br Hmac Signature

better-route: HMAC request signatures

Use this for server-to-server endpoints, webhooks, and back-channel calls where a bearer user token is not the right primitive. The middleware validates headers before the handler runs.

Pattern

use BetterRoute\Middleware\Auth\ArrayHmacSecretProvider;
use BetterRoute\Middleware\Auth\HmacSignatureMiddleware;

$hmac = new HmacSignatureMiddleware(
    secrets: new ArrayHmacSecretProvider([
        'primary' => getenv('MYAPP_WEBHOOK_SECRET'),
        'next' => getenv('MYAPP_WEBHOOK_SECRET_NEXT'),
    ]),
    signatureHeader: 'X-Signature',
    timestampHeader: 'X-Timestamp',
    keyIdHeader: 'X-Key-Id',
    replayWindowSeconds: 300,
    algorithm: 'sha256'
);

$router->post('/webhooks/provider', $handler)
    ->middleware([$hmac])
    ->publicRoute();

Canonical input

The signature input is:

timestamp + "\n" + method + "\n" + path + "\n" + sha256(body)

Default headers:

• X-Signature
• X-Timestamp
• X-Key-Id

Accepted signature encodings:

• lowercase hex
• uppercase hex
• base64
• base64url
• the same values prefixed with sha256=

Critical rules

• Unknown key ID fails closed.
• Missing signature/timestamp/key-id fails closed with 401.
• Timestamp outside replayWindowSeconds fails closed.
• Signature comparison uses Crypto::equals().
• Keep secrets outside code; use constants/env/options managed by the host application.
• HMAC authenticates the sender and request body. It does not make the route private at the WordPress permission layer; pair public webhook routes with ->publicRoute() deliberately.

Cross-references

• Use br-network-security if the same route also needs a CIDR allowlist.
• Use br-routes for publicRoute() vs protectedByMiddleware() intent.
• Use br-error-contract for 401 invalid_signature and stale_signature handling.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Lonsdale201
• Source: Lonsdale201/wp-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.