docs(plugin-authz): add authz skill and rule the plugin route examples - #541
Merged
Conversation
Plugin HTTP authz is now derived from routes (@path_rule + AuthzScope), but the plugin-* dev skills carried no authz guidance and several showed unruled route examples that now fail the OPA bundle build under on_invalid_plugin=hard_fail. - Add the plugin-authz skill (SKILL.md + examples.md): the recipe, permission id grammar, scope gate, caller kinds (PRINCIPAL vs SERVICE_PRINCIPAL), the job and function route factories, extra_permissions/extra_role_permissions, fail modes, and the verify commands. - Rule the route examples in creating-a-plugin, plugin-service (+ crud-example), plugin-job and plugin-function; add a service-principal note to plugin-controller. - Register plugin-authz in the package AGENTS.md skill index. Signed-off-by: Max Dubrinsky <mdubrinsky@nvidia.com>
Contributor
📝 WalkthroughWalkthroughThis PR is documentation-only, adding a new ChangesPlugin authorization documentation
Possibly related PRs
Suggested labels: Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (2)
packages/nemo_platform_plugin/src/nemo_platform_plugin/.agents/skills/plugin-authz/SKILL.md (1)
1-8: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd prerequisites before the guide body.
The page jumps straight into authz rules and recipes, but the doc guideline requires prerequisites at the top. The workspace/install assumptions currently only appear in
Verify.As per coding guidelines: “Always list prerequisites at the top of documentation pages before other content.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/nemo_platform_plugin/src/nemo_platform_plugin/.agents/skills/plugin-authz/SKILL.md` around lines 1 - 8, Add a short prerequisites section at the top of the plugin-authz guide before the main authz explanation in SKILL.md. Move the workspace/install assumptions currently mentioned under Verify into this new opening section, and keep the rest of the document starting with the route-based authorization overview. Use the existing SKILL.md headings/content flow as the reference point when inserting the prerequisites above the current body.Source: Coding guidelines
packages/nemo_platform_plugin/src/nemo_platform_plugin/.agents/skills/plugin-authz/examples.md (1)
1-24: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd prerequisites before the recipes.
This page starts with examples immediately, but the repo doc guideline requires prerequisites at the top. The repo-root/workspace-installed assumptions are only stated later in
Verify.As per coding guidelines: “Always list prerequisites at the top of documentation pages before other content.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/nemo_platform_plugin/src/nemo_platform_plugin/.agents/skills/plugin-authz/examples.md` around lines 1 - 24, The documentation starts with recipes before listing the assumptions needed to use them, so add a prerequisites section at the top of this page before the “plugin-authz recipes” content. Move the repo-root/workspace-installed assumptions from the later “Verify” area into that new prerequisites section, and keep the rest of the recipe sections unchanged.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In
`@packages/nemo_platform_plugin/src/nemo_platform_plugin/.agents/skills/plugin-authz/examples.md`:
- Around line 1-24: The documentation starts with recipes before listing the
assumptions needed to use them, so add a prerequisites section at the top of
this page before the “plugin-authz recipes” content. Move the
repo-root/workspace-installed assumptions from the later “Verify” area into that
new prerequisites section, and keep the rest of the recipe sections unchanged.
In
`@packages/nemo_platform_plugin/src/nemo_platform_plugin/.agents/skills/plugin-authz/SKILL.md`:
- Around line 1-8: Add a short prerequisites section at the top of the
plugin-authz guide before the main authz explanation in SKILL.md. Move the
workspace/install assumptions currently mentioned under Verify into this new
opening section, and keep the rest of the document starting with the route-based
authorization overview. Use the existing SKILL.md headings/content flow as the
reference point when inserting the prerequisites above the current body.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 56b92a0d-2299-45b7-8155-d3445cca238c
📒 Files selected for processing (9)
packages/nemo_platform_plugin/AGENTS.mdpackages/nemo_platform_plugin/src/nemo_platform_plugin/.agents/skills/creating-a-plugin/SKILL.mdpackages/nemo_platform_plugin/src/nemo_platform_plugin/.agents/skills/plugin-authz/SKILL.mdpackages/nemo_platform_plugin/src/nemo_platform_plugin/.agents/skills/plugin-authz/examples.mdpackages/nemo_platform_plugin/src/nemo_platform_plugin/.agents/skills/plugin-controller/SKILL.mdpackages/nemo_platform_plugin/src/nemo_platform_plugin/.agents/skills/plugin-function/SKILL.mdpackages/nemo_platform_plugin/src/nemo_platform_plugin/.agents/skills/plugin-job/SKILL.mdpackages/nemo_platform_plugin/src/nemo_platform_plugin/.agents/skills/plugin-service/SKILL.mdpackages/nemo_platform_plugin/src/nemo_platform_plugin/.agents/skills/plugin-service/crud-example.md
Contributor
|
Follow-up after functionally verifying the skill (a skill-only agent built a plugin whose authz derived clean) and reviewing caller-kind coverage. - Caller kinds: replace the prose with a positive classification table (what each setting does, which routes suit it), drop the ANON reference (dropped from the spec), and document that callers must be non-empty (callers=[] raises; "either" is [PRINCIPAL, SERVICE_PRINCIPAL]). - @path_rule: note stacking ORs only the caller dimension — stacked rules must share permissions (an OR of distinct permission sets is rejected). - Permission ids: clarify segments split on dots only (hyphens are fine within a segment, e.g. my-plugin.widgets.create). - examples.md: fix the service-principal recipe's entity-client import (was a local re-export the shown dependencies.py did not provide); point the job and function factory recipes at plugin-job / plugin-function for building the class; add a lightweight in-process tests/test_authz.py recipe. Signed-off-by: Max Dubrinsky <mdubrinsky@nvidia.com>
arpitsardhana
pushed a commit
that referenced
this pull request
Jul 9, 2026
#541) * docs(plugin-authz): add authz skill and rule the plugin route examples Plugin HTTP authz is now derived from routes (@path_rule + AuthzScope), but the plugin-* dev skills carried no authz guidance and several showed unruled route examples that now fail the OPA bundle build under on_invalid_plugin=hard_fail. - Add the plugin-authz skill (SKILL.md + examples.md): the recipe, permission id grammar, scope gate, caller kinds (PRINCIPAL vs SERVICE_PRINCIPAL), the job and function route factories, extra_permissions/extra_role_permissions, fail modes, and the verify commands. - Rule the route examples in creating-a-plugin, plugin-service (+ crud-example), plugin-job and plugin-function; add a service-principal note to plugin-controller. - Register plugin-authz in the package AGENTS.md skill index. Signed-off-by: Max Dubrinsky <mdubrinsky@nvidia.com> * docs(plugin-authz): refine caller-kind guidance and fix example gaps Follow-up after functionally verifying the skill (a skill-only agent built a plugin whose authz derived clean) and reviewing caller-kind coverage. - Caller kinds: replace the prose with a positive classification table (what each setting does, which routes suit it), drop the ANON reference (dropped from the spec), and document that callers must be non-empty (callers=[] raises; "either" is [PRINCIPAL, SERVICE_PRINCIPAL]). - @path_rule: note stacking ORs only the caller dimension — stacked rules must share permissions (an OR of distinct permission sets is rejected). - Permission ids: clarify segments split on dots only (hyphens are fine within a segment, e.g. my-plugin.widgets.create). - examples.md: fix the service-principal recipe's entity-client import (was a local re-export the shown dependencies.py did not provide); point the job and function factory recipes at plugin-job / plugin-function for building the class; add a lightweight in-process tests/test_authz.py recipe. Signed-off-by: Max Dubrinsky <mdubrinsky@nvidia.com> --------- Signed-off-by: Max Dubrinsky <mdubrinsky@nvidia.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Plugin HTTP authorization is now derived from routes (
@path_rule+AuthzScope, #332). Theplugin-*developer skills carried no authz guidance, and several taught route examples with no rule — following them today produces a plugin whose OPA bundle build hard-fails.This adds a canonical
plugin-authzskill and fixes the misleading examples.Changes
plugin-authzskill (SKILL.md+examples.md): the rule (every route needs a@path_ruleorhard_failrefuses the bundle), the recipe, theservice.resource.actionpermission grammar, the@AuthzScope.read/.writescope gate, caller kinds (PRINCIPALvsSERVICE_PRINCIPAL), the job/function route factories (authz=),extra_permissions/extra_role_permissions, the fail modes, and the verify commands.creating-a-plugin(the 5-step minimal service and the job/function factory calls),plugin-service(+crud-example.md),plugin-job,plugin-function; added a service-principal note toplugin-controller.plugin-authzin thenemo-platform-pluginpackageAGENTS.mdskill index (routing list + Available Skills).Why it matters
Under the new
on_invalid_plugin=hard_faildefault, an unruled route aborts the whole OPA bundle build and the platform 502s. An agent followingcreating-a-plugin's "minimal plugin in 5 steps" as written would ship a plugin that will not start.Verification
plugin-authzregistered in bothAGENTS.mdlists.authz.py, the example plugin, the deployments service-principal routes, the factory signatures) and was adversarially reviewed against source before landing.Summary by CodeRabbit