Br hmac signature

Skill Lonsdale201/wp-agent-skills/better-route/br-hmac-signature

A community-maintained collection of agent skills for WordPress plugin and theme development.

Install

npx -y skills add Lonsdale201/wp-agent-skills --skill br-hmac-signature

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

21 stars21 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Configure Better Route 1.1 HMAC authentication for webhooks and server-to-server REST requests. Use when signing request timestamps, methods, paths, raw bodies, optional query strings, rotating key IDs, or consuming the shared HMAC AuthContext identity.

SKILL.md

3.3 KB, as published. Nobody here has run it

Better Route HMAC request signatures

Use HMAC for a shared-secret webhook or back-channel client. Attach the middleware and mark the raw route as middleware-protected; HMAC is authentication, not a public-route exception.

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

$hmac = new HmacSignatureMiddleware(
    secrets: new ArrayHmacSecretProvider([
        'primary' => MY_PLUGIN_WEBHOOK_SECRET,
        'next' => MY_PLUGIN_WEBHOOK_SECRET_NEXT,
    ]),
    replayWindowSeconds: 300,
    algorithm: 'sha256',
    signQueryString: true
);

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

Canonical string

The client must sign the exact raw request body and construct:

timestamp + "\n" + UPPERCASE_METHOD + "\n" + path + "\n" + sha256(rawBody)

With signQueryString: true, append a fifth line containing the recursively key-sorted query encoded by PHP http_build_query(). Both client and server must use the same nested-array and space-encoding rules. Query parameters are unsigned by default, so enable this option or keep every security-relevant value in the signed body.

Default headers are X-Signature, X-Timestamp, and X-Key-Id. The signature accepts hex, Base64, or Base64URL, optionally prefixed with <algorithm>=. Prefer one documented client encoding even though the server accepts several.

Security rules

Generate high-entropy secrets and keep them out of source control and logs.
Rotate keys by accepting old and new key IDs briefly; remove the old key after rollout.
Use HTTPS. HMAC authenticates content but does not encrypt it.
A timestamp window limits delayed replay but does not prevent two identical requests inside the window. Combine writes with atomic idempotency or a single-use-token store when duplicate execution is unsafe.
Sign the raw transmitted bytes. JSON re-encoding, changed whitespace, or a different path causes a legitimate signature to fail.
Never choose the secret from request data except through a reviewed HmacSecretProviderInterface key-ID lookup.

After verification, Better Route 1.1 writes provider: hmac and subject: <key-id> into the shared auth context and adds an hmac attribute. Audit and rate-limit middleware can use that identity.

Test missing headers, unknown key ID, malformed and out-of-window timestamps, altered body/path/query, key rotation, and an unsigned-route configuration mistake.

Source references: src/Middleware/Auth/HmacSignatureMiddleware.php, src/Middleware/Auth/HmacSecretProviderInterface.php, src/Middleware/Auth/ArrayHmacSecretProvider.php.

References

Official documentation: https://lonsdale201.github.io/better-docs/docs/better-route/agents