Copilot commented on code in PR #13708:
URL: https://github.com/apache/trafficserver/pull/13708#discussion_r4052776357
##########
plugins/experimental/access_control/access_control.h:
##########
@@ -107,6 +107,17 @@ enum AccessTokenStatus {
const char *accessTokenStatusToString(const AccessTokenStatus &state);
+/**
+ * Validates whether a request path fails within the scope claim of an access
token.
+ * Matching is performed on normalized path segments. An empty or absent scope
is
+ * treated as unrestricted (returns true).
Review Comment:
The new API documentation says the function validates whether a request path
"fails within" the scope, which reverses/misstates the predicate and is
confusing for callers. Please change this to "falls within" (or otherwise state
that it returns true when the path is permitted).
##########
doc/admin-guide/plugins/access_control.en.rst:
##########
@@ -237,7 +237,7 @@ Query-Param-Style Named Claim format
* ``iat`` for `issued at time`_, `optional`
* ``tid`` for `token id`_, `optional`
* ``ver`` for `version`_, `optional`, defaults to ``ver=1`` if not
specified.
- * ``scope`` for `scope`_, `optional`, ignored by the current version of the
plugin, still not finalized (more applications and their use cases need to be
studied to finalize the format)
+ * ``scope`` for `scope`_, `optional`, A path-prefix scope that restricts
token use to matching request paths. Matching is performed on normalized path
segments;
Review Comment:
This sentence does not document two important parts of the implemented
contract: an absent/empty scope is unrestricted, and matching requires a
segment boundary (so `/reports` does not authorize `/reports2`). Without those
details, operators cannot safely predict how existing tokens and sibling paths
behave; please describe those semantics here, along with the configured
out-of-scope response if this is intended as the full scope documentation.
--
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]
