zjncs opened a new pull request, #5530:
URL: https://github.com/apache/rocketmq-dashboard/pull/5530
Fixes #5398
## What this adds
**`docs/mcp-hmac.md`** — the signing contract written down from the two
implementations (the Go client's `auth.go` even references `docs/mcp-hmac.md`
today — a dangling reference this PR also fixes):
- **Operator-facing guarantees**: opaque 401s (never revealing which check
failed), protected endpoints (`/api/mcp` + `/api/mcp/tools/call`), transport
assumptions (HTTPS on public endpoints; the client's
loopback/RFC1918/link-local HTTP exception and no-redirect policy).
- **Wire format**: `Authorization: rmq-hmac-sha256
Credential=<rfc3986-encoded key>, Signature=<64 lowercase hex>` +
`x-rmq-instance-id` + `x-rmq-timestamp`.
- **Canonical request**: the six-line string-to-sign, with the request
target **including the query string**, exactly as sent (no re-canonicalization
on either end).
- **Signature**: HMAC-SHA256 over UTF-8, lowercase hex, constant-time
comparison on the server.
- **Clock-skew rules**: epoch millis, ±5 minutes, non-numeric treated as
stale; per-attempt fresh timestamps so retries need no special handling.
- **Revisions**: the algorithm token is the revision identifier —
incompatible changes mint a new token (`rmq-hmac-sha256/2`), the server accepts
exactly one revision, and the previous revision should be kept for one
minor-release compatibility window (deprecation note in release notes). This
answers the issue's "how future revisions should evolve".
- **Golden vectors**: the shared vector file is the conformance mechanism —
any canonicalization change must update the vectors in the same commit.
**`McpHmacGoldenVectorTest`** — the Java server now recomputes every vector
in `rmqctl/internal/studio/testdata/auth-hmac-vectors.json` through
`McpAuthenticator.canonicalRequest` itself, closing the gap the issue calls out
("Shared golden vectors and client/server conformance tests"): previously only
the Go client consumed the vectors; the Java test computed its own one-off
values.
## Verification
- `McpHmacGoldenVectorTest`: **2/2 passed** (every vector's canonical
request and signature match byte-for-byte; constant-time comparison contract
pinned);
- **mutation** (swap `instanceId`/`timestamp` lines in the server's
canonical request): the test **fails** on the first vector with the mismatch
evidence; restore: 2/2 green — the vectors genuinely constrain both ends;
- Go client conformance: `go test ./internal/studio/ -run
TestSigningRoundTripperMatchesGoldenVectors` → **ok** (both ends green against
the same file);
- regression: `McpCredentialAuthenticationTest` **19/19** unchanged.
```bash
cd server && mvn test -Dtest=McpHmacGoldenVectorTest
cd rmqctl && go test ./internal/studio/ -run
TestSigningRoundTripperMatchesGoldenVectors
```
The unsupported-version behavior and deprecation guidance sections propose a
concrete policy for maintainer confirmation — happy to adjust wording per
review.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
