You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tooling.apache.org by "sbp (via GitHub)" <gi...@apache.org> on 2026/04/14 19:28:59 UTC
[I] Add explicit authentication level decorators for API endpoint functions (tooling-trusted-releases)
sbp opened a new issue, #1169:
URL: https://github.com/apache/tooling-trusted-releases/issues/1169
Could be something like:
```
@api.auth.public
@api.auth.bearer
@api.auth.trusted_publisher
@api.auth.pat
```
Then, there should be tests checking when a route does not have any explicit decorator. That way we don't have the "fail open" problem where a route that we add without an authentication decorator is automatically public.
This issue is derived from the second half of #1040.
--
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: dev-unsubscribe@tooling.apache.org.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tooling.apache.org
For additional commands, e-mail: dev-help@tooling.apache.org
Re: [I] Add explicit authentication level decorators for API endpoint functions (tooling-trusted-releases)
Posted by "asf-tooling (via GitHub)" <gi...@apache.org>.
asf-tooling commented on issue #1169:
URL: https://github.com/apache/tooling-trusted-releases/issues/1169#issuecomment-4404139851
<!-- gofannon-issue-triage-bot v2 skip -->
_Automated triage — analyzed at `main@837830e8`_
**Classification:** `pr_in_progress`
This issue appears to be addressed by open PR: #1207. The agent skipped detailed code analysis to avoid duplicating effort.
Re-run triage after the PR merges or closes if you want a fresh analysis from the agent.
---
*Draft from a triage agent. A human reviewer should validate.*
--
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: dev-unsubscribe@tooling.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tooling.apache.org
For additional commands, e-mail: dev-help@tooling.apache.org
Re: [I] Add explicit authentication level decorators for API endpoint functions (tooling-trusted-releases)
Posted by "sbp (via GitHub)" <gi...@apache.org>.
sbp commented on issue #1169:
URL: https://github.com/apache/tooling-trusted-releases/issues/1169#issuecomment-4289357404
These could be three commits in one PR, rather than three PRs.
Answers to the open questions:
1. Yeah, `body_oidc`.
2. As long as this follows the current public list, that's fine.
3. No, this is API only. All admin routes are, of course, admin only so that would be handled in the blueprint not at the route decorator level. For GET and POST routes, we should perhaps do something like this, but in another PR.
--
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: dev-unsubscribe@tooling.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tooling.apache.org
For additional commands, e-mail: dev-help@tooling.apache.org
Re: [I] Add explicit authentication level decorators for API endpoint functions (tooling-trusted-releases)
Posted by "dave2wave (via GitHub)" <gi...@apache.org>.
dave2wave commented on issue #1169:
URL: https://github.com/apache/tooling-trusted-releases/issues/1169#issuecomment-4246606884
I agree.
Would `@api.auth.oidc` be better and more succinct than `@api.auth.trusted_publisher`?
--
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: dev-unsubscribe@tooling.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tooling.apache.org
For additional commands, e-mail: dev-help@tooling.apache.org
Re: [I] Add explicit authentication level decorators for API endpoint functions (tooling-trusted-releases)
Posted by "sbp (via GitHub)" <gi...@apache.org>.
sbp commented on issue #1169:
URL: https://github.com/apache/tooling-trusted-releases/issues/1169#issuecomment-4298687166
Yeah, we've decided not to do regular GET/POST because they don't have the same lack of failing closed.
--
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: dev-unsubscribe@tooling.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tooling.apache.org
For additional commands, e-mail: dev-help@tooling.apache.org
Re: [I] Add explicit authentication level decorators for API endpoint functions (tooling-trusted-releases)
Posted by "andrewmusselman (via GitHub)" <gi...@apache.org>.
andrewmusselman commented on issue #1169:
URL: https://github.com/apache/tooling-trusted-releases/issues/1169#issuecomment-4285070912
@sbp @dave2wave proposal here for discussion
# Proposal: Explicit Authentication Level Decorators for API Endpoints
This is a plan for [#1169](./1169). Feedback welcome before any PR lands.
## Goals
1. Every `@api.typed` route must declare exactly one authentication level with a visible, grep-able decorator.
2. Forgetting the decorator must fail loudly at import time, not silently ship as a public route.
3. Changes to any route's auth level must be visible in a diff that security reviewers can block.
## Current state
All API endpoints live in `atr/api/__init__.py` and are registered via `@api.typed` from `atr/blueprints/api.py`. There are 46 such endpoints. Four de facto auth patterns exist today, but only one is declarative:
| Pattern | How it's expressed today | Count |
|---|---|---|
| Public | _no decorator_ | 20 |
| Bearer JWT (ATR-issued) | `@jwtoken.require` | 18 |
| Trusted Publisher OIDC | _no decorator_ — validated inside the function via `interaction.trusted_jwt(...)` or `validate_trusted_jwt(...)` | 7 |
| PAT → JWT exchange | _no decorator_ — PAT validated inside the function | 1 |
This is exactly the fail-open risk @sbp called out: a new route with no decorator is indistinguishable from an intentionally-public route or a body-auth route.
## Proposed decorators
Add a new module `atr/blueprints/api_auth.py`, exposed on the existing `api` namespace so the spelling matches [#1169](./1169):
- `@api.auth.public` — marker only, no behavior change. Explicit opt-in to "no auth".
- `@api.auth.bearer` — wraps `jwtoken.require` and folds in `@quart_schema.security_scheme([{"BearerAuth": []}])` so OpenAPI stops being a separate concern.
- `@api.auth.body_oidc` — validates a Trusted Publisher JWT from the request body before the handler runs, and exposes the verified payload on `quart.g`. Replaces the in-body `validate_trusted_jwt(...)` call.
- `@api.auth.pat` — for `jwt_create`; marker only initially, with room to move the PAT lookup into the decorator later.
(Picking `body_oidc` over `trusted_publisher` per the suggestion in the thread.)
Each decorator stamps a sentinel attribute on the function, `_api_auth_level ∈ {"public", "bearer", "body_oidc", "pat"}`. That attribute is the checkable marker.
## Enforcement: import-time, fail-closed
In `atr/blueprints/api.py`, `typed()` inspects the wrapped function and **raises `TypeError` at import time** if `_api_auth_level` is missing:
```python
def typed(func):
original = inspect.unwrap(func)
level = _detect_auth_level(func, original)
if level is None:
raise TypeError(
f"API route {original.__name__!r} is missing an auth decorator. "
"Apply exactly one of @api.auth.public, @api.auth.bearer, "
"@api.auth.body_oidc, @api.auth.pat."
)
# ... existing body ...
```
That single line is what fixes the fail-open problem: a forgotten decorator cannot register a route.
Decorator order is fixed and documented: `@api.typed` on the outside, then `@api.auth.<level>`, then any `@quart_schema` / `@rate_limiter` decorators closer to the function.
## Coverage + drift tests
Two new tests in `tests/unit/test_api_auth_decorators.py`:
1. **Coverage test** — walk every registered API route and assert `_api_auth_level` is set to one of the four valid values. Any new undecorated route fails CI.
2. **Registry drift test** — a checked-in `tests/unit/api_auth_registry.yaml` mapping URL path → expected level. The test asserts live registration matches. Any auth-level *change* becomes a visible diff that a reviewer can block.
```yaml
# tests/unit/api_auth_registry.yaml — excerpt
# Changing an auth level here requires security review.
/api/committees/list: public
/api/ignore/add: bearer
/api/publisher/ssh/register: body_oidc
/api/jwt/create: pat
```
A third, behavioral test hits one representative endpoint per level without credentials: 200 for `public`, 401 for the rest.
## Audit of existing endpoints (what each one will get)
**Bearer (18):** `distribution_record`, `ignore_add`, `ignore_delete`, `key_add`, `key_delete`, `keys_upload`, `policy_update`, `release_announce`, `release_create`, `release_delete`, `release_upload`, `signature_provenance`, `ssh_key_add`, `ssh_key_delete`, `user_info`, `vote_resolve`, `vote_start`, `vote_tabulate` — all already `@jwtoken.require`, pure rename.
**body_oidc (7):** `distribute_ssh_register`, `distribution_record_from_workflow`, `publisher_distribution_record`, `publisher_release_announce`, `publisher_ssh_register`, `publisher_vote_resolve`, `update_distribution_task_status`.
**pat (1):** `jwt_create`.
**public (20):** `checks_list`, `checks_list_revision`, `checks_ongoing`, `committee_get`, `committee_keys`, `committee_projects`, `committees_list`, `ignore_list`, `key_get`, `keys_user`, `policy_get`, `project_get`, `project_releases`, `projects_list`, `release_get`, `release_paths`, `release_revisions`, `releases_list`, `ssh_keys_list`, `users_list`.
The `public` list deserves a second look from someone who knows the threat model — nothing there currently requires auth, but please flag anything I've misjudged.
## Rollout: three PRs
Split to keep each reviewable in isolation.
### PR 1 — scaffolding, no behavior change
- Add `atr/blueprints/api_auth.py` with the four decorators (all of them inert at this stage — `bearer` just calls `jwtoken.require`, `body_oidc` and `pat` only set the marker).
- Add the import-time enforcement in `atr/blueprints/api.py` `typed()`.
- Mark every existing route with its correct decorator. `@jwtoken.require` stays where it is; `@api.auth.bearer` sits alongside it for now.
- Add `tests/unit/test_api_auth_decorators.py` with the coverage test.
**Behaviorally a no-op.** The only new failure mode is "route registered without auth decorator → `TypeError`".
### PR 2 — fold `bearer` auth into the decorator
- `@api.auth.bearer` replaces both `@jwtoken.require` and `@quart_schema.security_scheme([{"BearerAuth": []}])` everywhere.
- Remove the now-redundant decorators from the 18 bearer endpoints.
- Add a behavioral test that hits a bearer endpoint without credentials and confirms 401.
This is the "one decorator, one meaning" consolidation for the biggest group.
### PR 3 — `body_oidc` and `pat` + registry
- `@api.auth.body_oidc` performs the `validate_trusted_jwt(publisher, jwt)` check before the handler runs and exposes the verified payload on `quart.g`. Handlers drop their inline `trusted_jwt(...)` preamble where possible (the phase-specific checks stay in the handler — see "Edge cases" below).
- `@api.auth.pat` gets the equivalent treatment for `jwt_create`.
- Add `tests/unit/api_auth_registry.yaml` and the drift test.
- Add behavioral tests for `body_oidc` and `pat` levels.
- Update `docs/authentication-security.html` to document the four levels.
## Edge cases worth flagging now
- **`distribute_ssh_register` / `distribution_record_from_workflow`** use `trusted_jwt_for_dist`, which takes `asf_uid`, `project_key`, `version_key` and does a phase check. The decorator should handle only the token-signature / issuer / audience / claims check; the phase and project lookup stay in the handler. Simpler and less magic.
- **`update_distribution_task_status`** requires `asf_uid is None` (ATR-own workflow only). That stays as a handler check. If this pattern spreads, we can add a `body_oidc_atr_only` variant later.
- **`publisher_distribution_record`** currently tries `TrustedProjectPhase.FINISH`, falls back to `COMPOSE`. That fallback belongs in the handler, not the decorator.
- **Rate limiting** stays orthogonal. Auth levels are about *who* can call; `@rate_limiter.rate_limit` is about *how often*. Don't conflate them.
- **`/api/openapi.json`** is auto-generated by `quart_schema` and doesn't go through `@api.typed`. The coverage test filters it explicitly rather than silently excluding unknown endpoints.
## Open questions
1. Final name: `body_oidc` reads well against `bearer` and `pat`. Confirm?
2. Should the `public` audit list be blessed by a security reviewer before PR 1 lands, or is the registry file in PR 3 enough?
3. Are admin endpoints (`atr/admin/`) in scope? They don't appear to use `@api.typed`, but if they're exposed over HTTP they probably deserve the same treatment in a follow-up.
--
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: dev-unsubscribe@tooling.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tooling.apache.org
For additional commands, e-mail: dev-help@tooling.apache.org
Re: [I] Add explicit authentication level decorators for API endpoint functions (tooling-trusted-releases)
Posted by "dave2wave (via GitHub)" <gi...@apache.org>.
dave2wave commented on issue #1169:
URL: https://github.com/apache/tooling-trusted-releases/issues/1169#issuecomment-4289691798
> 3. No, this is API only. All admin routes are, of course, admin only so that would be handled in the blueprint not at the route decorator level. For GET and POST routes, we should perhaps do something like this, but in another PR.
I think that we have covered the non-API endpoints properly and we would need to discuss what benefits would be had by refactoring these at this time. We have to get to Beta and stop making extra work.
--
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: dev-unsubscribe@tooling.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tooling.apache.org
For additional commands, e-mail: dev-help@tooling.apache.org
Re: [I] Add explicit authentication level decorators for API endpoint functions (tooling-trusted-releases)
Posted by "dave2wave (via GitHub)" <gi...@apache.org>.
dave2wave closed issue #1169: Add explicit authentication level decorators for API endpoint functions
URL: https://github.com/apache/tooling-trusted-releases/issues/1169
--
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: dev-unsubscribe@tooling.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tooling.apache.org
For additional commands, e-mail: dev-help@tooling.apache.org
Re: [I] Add explicit authentication level decorators for API endpoint functions (tooling-trusted-releases)
Posted by "sbp (via GitHub)" <gi...@apache.org>.
sbp commented on issue #1169:
URL: https://github.com/apache/tooling-trusted-releases/issues/1169#issuecomment-4246743376
Yeah, good idea, or even `@api.auth.body_oidc` perhaps, because as I recall the audit tool is always stumbling on how that works (that it's a credential we send in the body rather than in a header).
--
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: dev-unsubscribe@tooling.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tooling.apache.org
For additional commands, e-mail: dev-help@tooling.apache.org