Lock JWT-claims call shape and document GetEntryClaims posture

Add `TestGetEntryClaims_PassesJWTClaimsToService` so the JWT-bearing
call shape (four mock matchers: ctx + entryType + name + jwtClaims) is
covered. The existing table test uses three matchers and would silently
break if the handler started passing a third option; the new case
locks the contract in place.

Also expand the `getEntryClaims` godoc to call out the authorization
model explicitly: role gate in middleware, JWT-subset check in the
service layer (mirrors the matching PUT), and the anonymous-mode
short-circuit. Note that the nil-claims-to-{} normalisation is dead
code in authz mode (publish forbids empty claims per auth.md §6 and
the gate denies them per §4) — so future readers don't assume it's
load-bearing for the authz path.

Author: rdimitrov

internal/api/v1/entries.go

@@ -192,7 +192,21 @@ type entryClaimsResponse struct {
 	Claims map[string]any `json:"claims"`
 }
 
-// getEntryClaims handles GET /v1/entries/{type}/{name}/claims
+// getEntryClaims handles GET /v1/entries/{type}/{name}/claims.
+//
+// Authorization model:
+//   - manageEntries role gate runs in middleware (see routes.go).
+//   - Service-layer JWT subset check denies cross-team reads (403) when authz
+//     is enabled, mirroring the matching PUT.
+//   - Anonymous mode (no JWT in context): the handler skips WithJWTClaims, the
+//     gate short-circuits, and any caller reads any entry's claims. Intended,
+//     but worth knowing if you ever run partial-anonymous deployments.
+//
+// The response envelope `{"claims": {...}}` is always a non-nil JSON object —
+// the impl normalises a missing/nil claims blob to `map[string]any{}`. Under
+// authz, that branch is unreachable in practice (publish forbids empty claims
+// per auth.md §6, and the gate denies empty-claim rows per §4); the
+// normalisation is for the auth-off / synced-source case.
 //
 // @Summary		Get entry claims
 // @Description	Get the claims for a published entry name. Claims are stored at the

internal/api/v1/entries_test.go

@@ -629,6 +629,39 @@ func TestGetEntryClaims(t *testing.T) {
 	}
 }
 
+// TestGetEntryClaims_PassesJWTClaimsToService verifies the handler plumbs JWT
+// claims through to the service when they're present in the request context.
+// Without this case, the table test above would let a regression slip — its
+// mock expectations use exactly three matchers (ctx + 2 options) and would
+// fail at runtime if the handler started passing a third option silently.
+func TestGetEntryClaims_PassesJWTClaimsToService(t *testing.T) {
+	t.Parallel()
+
+	ctrl := gomock.NewController(t)
+	t.Cleanup(ctrl.Finish)
+
+	mockSvc := mocks.NewMockRegistryService(ctrl)
+	// Four matchers: ctx + WithEntryType + WithName + WithJWTClaims.
+	mockSvc.EXPECT().GetEntryClaims(gomock.Any(), gomock.Any(), gomock.Any(), gomock.Any()).
+		Return(map[string]any{"org": "acme", "team": "platform"}, nil)
+
+	router := Router(mockSvc, nil)
+	req, err := http.NewRequest(http.MethodGet, "/entries/server/test%2Fserver/claims", nil)
+	require.NoError(t, err)
+	req = req.WithContext(auth.ContextWithClaims(
+		req.Context(), jwt.MapClaims{"org": "acme", "team": "platform"},
+	))
+
+	rr := httptest.NewRecorder()
+	router.ServeHTTP(rr, req)
+
+	assert.Equal(t, http.StatusOK, rr.Code)
+
+	var resp entryClaimsResponse
+	require.NoError(t, json.Unmarshal(rr.Body.Bytes(), &resp))
+	assert.Equal(t, map[string]any{"org": "acme", "team": "platform"}, resp.Claims)
+}
+
 // mustMarshal is a test helper that marshals v to JSON or panics.
 func mustMarshal(v any) []byte {
 	b, err := json.Marshal(v)