# Plugin Authz

> Plugin HTTP Authorization (path_rule / AuthzScope)

- Skill: `nvidia-nemo/plugin-authz` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add nvidia-nemo/plugin-authz`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nvidia-nemo/plugin-authz/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: NVIDIA NeMo (https://skillmd.com/u/nvidia-nemo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nvidia-nemo/plugin-authz

---


# Plugin HTTP Authorization (path_rule / AuthzScope)

Authz is derived *entirely from the routes*. Each handler carries two orthogonal decorators — a `@path_rule` (who may call + what they must hold) and an `@AuthzScope.read`/`.write` (the OAuth scope gate). The platform reads them off the mounted routes to build the permission catalog, the per-endpoint bindings, and the OPA bundle. There is no separate permission list to keep in sync.

## THE RULE

Every plugin HTTP route MUST carry a `@path_rule` — directly, or via a route factory you passed `authz=` to. A route with no rule is a validation error: the offending routes are emitted as explicit **deny** markers (they override every allow, including the service `*` wildcard and the PlatformAdmin bypass), and under the default `on_invalid_plugin="hard_fail"` the auth service **refuses to build the OPA bundle** — the platform 502s rather than silently fencing the route.

If you add a route, you add a rule. If the platform starts 502-ing after you touch a plugin, suspect an unruled route first.

## Recipe — hand-written route

```python
from nemo_platform_plugin.authz import AuthzScope, CallerKind, PermissionSet, path_rule, perm

scope = AuthzScope("myplugin")                 # owns scopes myplugin:read / myplugin:write

class ItemPerms(PermissionSet, namespace="myplugin.items"):
    READ = perm("Read an item")                # id -> "myplugin.items.read"

@router.get("/v2/workspaces/{workspace}/items/{name}")
@scope.read                                    # OAuth scope gate
@path_rule(callers=[CallerKind.PRINCIPAL], permissions=[ItemPerms.READ])
async def get_item(workspace: str, name: str) -> Item: ...
```

**Decorator order:** `@router.<method>` is the OUTERMOST (top) decorator; `@scope.read` and `@path_rule` sit under it. Their order *relative to each other* does not matter — both only stamp attributes on the handler and return it unchanged (identity survives FastAPI's `include_router(prefix=...)` rebasing).

## `@path_rule` — callers + permissions

```python
@path_rule(callers=[CallerKind.PRINCIPAL], permissions=[ItemPerms.READ, ItemPerms.WRITE])
```

- Within a rule, `callers` are **OR**'d and `permissions` are **AND**'d.
- `callers` is **required and non-empty** — there is no `callers=[]` (it raises at import). To allow more than one caller kind, list them in one rule: `callers=[CallerKind.PRINCIPAL, CallerKind.SERVICE_PRINCIPAL]`.
- `permissions` may be `[]` for an authenticated-but-permissionless route (e.g. `/healthz`, a blob `PUT`).
- Stacking `@path_rule` on one handler adds OR-alternatives, but **v1 ORs only the caller dimension**: stacked rules must share the same `permissions` (an OR of *distinct* permission sets is rejected at derivation). "PRINCIPAL needs A, SERVICE_PRINCIPAL needs B" on one route isn't expressible — use one rule with shared permissions.
- Reference `PermissionSet` members, **never bare strings** — a string raises `TypeError` at import, so a permission typo can't reach the policy layer.

## Permission ids — `PermissionSet` + `perm()`

Id grammar is `<service>.<resource>.<action>`, joined from parts. The `<service>` (first segment) MUST equal `NemoService.name` — that namespace fence is enforced, or the whole plugin fails closed. Segments split on dots only; hyphens are fine *within* a segment, so a hyphenated name like `my-plugin` yields `my-plugin.widgets.create` — three segments (`my-plugin` / `widgets` / `create`), not four.

```python
class ItemPerms(PermissionSet, namespace="myplugin.items"):
    CREATE = perm("Create an item")                      # id -> "myplugin.items.create"
    STATUS_UPDATE = perm("Set observed status",
                         suffix="status.update")          # id -> "myplugin.items.status.update"
```

- Inside `PermissionSet(namespace="a.b")`, `perm("desc")` gives id `a.b.<member-name-lowercased>`.
- `perm("desc", suffix="configs.create")` mints a compound id `a.b.configs.create`.
- `PermissionSet.all()` returns every member (handy for `extra_permissions`).

## `@AuthzScope.read` / `.write` — the scope gate

A route carries **exactly one** OAuth scope, declared separately from `@path_rule`. `AuthzScope("agents")` owns `agents:read` / `agents:write` (each expands to `["<area>:<verb>", "platform:<verb>"]`). Re-stamping the same scope is idempotent; a *different* scope on the same handler is a `ValueError` at import.

Mint permissions off the same scope when the permission namespace nests deeper than the scope:

```python
AuthzScope("agents").child("deployments").permission("create", description="...")
# -> Permission id "agents.deployments.create"; the OAuth scope stays "agents"
```

Share one `AuthzScope` across a plugin's route modules (define it in a small `authz.py` and import it) so the scope and namespace live in one place.

## Caller kinds — who may call the route

`callers` is a required, non-empty list on every `@path_rule`; it names which kinds of authenticated caller the rule applies to (multiple are OR'd). Caller-kind is a PDP subject attribute enforced in Rego, not a permission.

| Set `callers` to | Satisfied by | Use it for |
|---|---|---|
| `[CallerKind.PRINCIPAL]` | a normal authenticated user (a human, or any user token) | the baseline — user-facing CRUD, reads, and actions a person invokes |
| `[CallerKind.SERVICE_PRINCIPAL]` | a caller whose id is prefixed `service:` (another service or a controller) | machine-to-machine routes a user must never call directly, e.g. a controller writing observed status |
| `[CallerKind.PRINCIPAL, CallerKind.SERVICE_PRINCIPAL]` | either of the above | routes hit by both people and services (e.g. a read a controller also consumes) |

If you are not writing a machine-only route, use `PRINCIPAL` — it is the baseline posture, and every rule states its callers explicitly (there is no "unset" at the `@path_rule` level). Pinning a route to `SERVICE_PRINCIPAL` alone denies a human user even when they hold the right permission. There is no anonymous or public caller kind: a plugin route always requires an authenticated caller, and genuinely public endpoints are core-infra bypasses, not plugin routes.

The deployments controller-status `PUT` is the canonical service-principal-only route — only the controller (`service:...`) may write observed status:

```python
@router.put("/deployments/{name}/status", response_model=Deployment)
@scope.write
@path_rule(callers=[CallerKind.SERVICE_PRINCIPAL], permissions=[DeploymentPerms.STATUS_UPDATE])
async def update_deployment_status(
    workspace: str,
    name: str,
    body: UpdateDeploymentStatusRequest,
    _: None = Depends(require_service_principal),   # 403s a non-service caller in-handler
    entity_client: NemoEntitiesClient = Depends(get_entity_client),
) -> Deployment: ...
```

`DeploymentPerms.STATUS_UPDATE = perm("Update deployment observed status (controller)", suffix="status.update")` under `namespace="deployments.deployments"` → id `deployments.deployments.status.update`.

## Route factories — pass `authz=` or the routes are UNRULED

`add_job_routes` / `add_function_routes` stamp the rule for you, but the `authz=` kwarg **defaults to `None`** — omit it and every generated route is unruled (denied fail-closed at bundle time).

```python
from nemo_platform_plugin.jobs.routes import add_job_routes
from nemo_platform_plugin.functions.routes import add_function_routes

add_job_routes(MyJob, authz=AuthzScope("myplugin"))
add_function_routes(MyFn, authz=AuthzScope("myplugin"), permission_description="Invoke MyFn")
```

Invoking a function is a **write** action: the factory mints a PRINCIPAL permission `<namespace>.<function-name>` and stamps `@scope.write`. `permission_description` defaults to the function's own description and **requires `authz`** (supplying it alone is a `ValueError`).

## Escape hatches — permissions with no 1:1 route

Override on your `NemoService` for permissions that aren't attached to a route (checked in middleware, or granted to a role the heuristic misses):

```python
from nemo_platform_plugin.authz import Permission

def extra_permissions(self) -> list[Permission]: ...
def extra_role_permissions(self) -> dict[str, list[Permission]]: ...
```

**Default role-grant heuristic:** ids ending `.list` or `.read` → Viewer + Editor; everything else → Editor only. Use `extra_role_permissions` to reach a role the heuristic wouldn't — e.g. granting a Viewer an `.invoke` permission (its suffix isn't `read`). Grants are **unioned** with the defaults (never subtractive), each granted permission is also auto-registered in the catalog (no need to also list it in `extra_permissions`), and every permission must live in this service's own namespace or the whole plugin fails closed.

## Fail modes — `NMP_AUTH_ON_INVALID_PLUGIN`

The offending routes are *always* emitted as explicit denies; the auth-service config field `on_invalid_plugin` (env `NMP_AUTH_ON_INVALID_PLUGIN`, prefix `NMP_AUTH_`) only controls the blast radius:

| Value | Behaviour |
|---|---|
| `hard_fail` (default) | Refuse to build the OPA bundle — fail closed at the platform level (platform 502s). |
| `quarantine` | Deny the whole offending plugin, but keep the platform up. |
| `deny_route` | Deny only the bad routes. |

A deployment loading dynamically-discovered or third-party plugins CI never vetted can downgrade to `quarantine` / `deny_route` so one bad plugin can't wedge the platform.

## Verify

```bash
# From repo root, workspace installed. Reports 0 degraded plugins when every route is ruled:
uv run python services/core/auth/scripts/auth-tools.py sync-plugins --dry-run

make build-policy && make test-policy
```

> **Local dev:** `services/core/auth/.../assets/policy.wasm` is a gitignored build artifact. Run `make build-policy` after pulling authz/Rego changes, otherwise `test_embedded_pdp.py` fails against a stale copy (misleading `sprintf` / fence-fails-open errors).

For a fast in-process check with no running platform, add a `tests/test_authz.py` that derives your service's contribution and asserts it's clean (copy any plugin's `tests/test_authz.py`):

```python
from nemo_platform_plugin.authz_discovery import _derive_service_contribution

def test_all_routes_are_ruled():
    contrib, errors, _warnings = _derive_service_contribution(MyService())
    assert not errors
    assert not any(m.deny for methods in contrib.endpoints.values() for m in methods.values())
```

## Migrating off `get_authz_contribution`

The old surface is gone: the `get_authz_contribution()` classmethod and the `nemo.authz` entry point were removed. To migrate a plugin:

1. Delete `get_authz_contribution()` and drop the `nemo.authz` entry point.
2. Move each permission id into a `PermissionSet` — **ids are preserved**, so existing role grants do not change.
3. Attach `@path_rule` plus `@scope.read` / `@scope.write` to every handler (or `authz=` on the route factory).

## See Also

- [`examples.md`](examples.md) — full copy-paste recipes (hand-written CRUD, service-principal status route, job/function factory wiring, escape hatches)
- [`../plugin-service/SKILL.md`](../plugin-service/SKILL.md) — building the `NemoService` and its routers
- [`../plugin-job/SKILL.md`](../plugin-job/SKILL.md) — `add_job_routes` and job wiring
- [`../plugin-function/SKILL.md`](../plugin-function/SKILL.md) — `add_function_routes` and function wiring
- [`../plugin-controller/SKILL.md`](../plugin-controller/SKILL.md) — the service-principal side that writes observed status