br-hmac-signature

Name: br-hmac-signature
Author: Lonsdale201

21stars1forks

How to install br-hmac-signature?

lonsdale201/wp-agent-skills/br-hmac-signature

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

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.md

1	# Better Route HMAC request signatures
2
3	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.
4
5	```php
6	use BetterRoute\Middleware\Auth\ArrayHmacSecretProvider;
7	use BetterRoute\Middleware\Auth\HmacSignatureMiddleware;
8
9	$hmac = new HmacSignatureMiddleware(
10	secrets: new ArrayHmacSecretProvider([
11	'primary' => MY_PLUGIN_WEBHOOK_SECRET,
12	'next' => MY_PLUGIN_WEBHOOK_SECRET_NEXT,
13	]),
14	replayWindowSeconds: 300,
15	algorithm: 'sha256',
16	signQueryString: true
17	);
18
19	$router->post('/webhooks/provider', $handler)
20	->middleware([$hmac])
21	->protectedByMiddleware('hmacAuth');
22	```
23
24	## Canonical string
25
26	The client must sign the exact raw request body and construct:
27
28	```text
29	timestamp + "\n" + UPPERCASE_METHOD + "\n" + path + "\n" + sha256(rawBody)
30	```
31
32	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.
33
34	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.
35
36	## Security rules
37
38	- Generate high-entropy secrets and keep them out of source control and logs.
39	- Rotate keys by accepting old and new key IDs briefly; remove the old key after rollout.
40	- Use HTTPS. HMAC authenticates content but does not encrypt it.
41	- 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.
42	- Sign the raw transmitted bytes. JSON re-encoding, changed whitespace, or a different path causes a legitimate signature to fail.
43	- Never choose the secret from request data except through a reviewed `HmacSecretProviderInterface` key-ID lookup.
44
45	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.
46
47	Test missing headers, unknown key ID, malformed and out-of-window timestamps, altered body/path/query, key rotation, and an unsigned-route configuration mistake.
48
49	Source references: `src/Middleware/Auth/HmacSignatureMiddleware.php`, `src/Middleware/Auth/HmacSecretProviderInterface.php`, `src/Middleware/Auth/ArrayHmacSecretProvider.php`.
50
51	## References
52
53	- Official documentation: <https://lonsdale201.github.io/better-docs/docs/better-route/agents>

People who liked this also viewed

6 picks

Type

br-hmac-signature

21stars1forks

View on GitHub

How to install br-hmac-signature?

lonsdale201/wp-agent-skills/br-hmac-signature

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

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Better Route HMAC request signatures
2
3	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.
4
5	```php
6	use BetterRoute\Middleware\Auth\ArrayHmacSecretProvider;
7	use BetterRoute\Middleware\Auth\HmacSignatureMiddleware;
8
9	$hmac = new HmacSignatureMiddleware(
10	secrets: new ArrayHmacSecretProvider([
11	'primary' => MY_PLUGIN_WEBHOOK_SECRET,
12	'next' => MY_PLUGIN_WEBHOOK_SECRET_NEXT,
13	]),
14	replayWindowSeconds: 300,
15	algorithm: 'sha256',
16	signQueryString: true
17	);
18
19	$router->post('/webhooks/provider', $handler)
20	->middleware([$hmac])
21	->protectedByMiddleware('hmacAuth');
22	```
23
24	## Canonical string
25
26	The client must sign the exact raw request body and construct:
27
28	```text
29	timestamp + "\n" + UPPERCASE_METHOD + "\n" + path + "\n" + sha256(rawBody)
30	```
31
32	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.
33
34	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.
35
36	## Security rules
37
38	- Generate high-entropy secrets and keep them out of source control and logs.
39	- Rotate keys by accepting old and new key IDs briefly; remove the old key after rollout.
40	- Use HTTPS. HMAC authenticates content but does not encrypt it.
41	- 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.
42	- Sign the raw transmitted bytes. JSON re-encoding, changed whitespace, or a different path causes a legitimate signature to fail.
43	- Never choose the secret from request data except through a reviewed `HmacSecretProviderInterface` key-ID lookup.
44
45	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.
46
47	Test missing headers, unknown key ID, malformed and out-of-window timestamps, altered body/path/query, key rotation, and an unsigned-route configuration mistake.
48
49	Source references: `src/Middleware/Auth/HmacSignatureMiddleware.php`, `src/Middleware/Auth/HmacSecretProviderInterface.php`, `src/Middleware/Auth/ArrayHmacSecretProvider.php`.
50
51	## References
52
53	- Official documentation: <https://lonsdale201.github.io/better-docs/docs/better-route/agents>

People who liked this also viewed

6 picks

Type