sbp commented on code in PR #1261: URL: https://github.com/apache/tooling-trusted-releases/pull/1261#discussion_r3289282058
########## atr/docs/api-documentation-policy.md: ########## @@ -0,0 +1,79 @@ +# 3.16. API documentation policy + +**Up**: `3.` [Developer guide](developer-guide) + +**Prev**: `3.15.` [TLS security configuration](tls-security-configuration) + +**Next**: `3.17.` [ASFQuart usage](asfquart-usage) + +**Sections**: + +* [Overview](#overview) +* [Decision](#decision) +* [Rationale](#rationale) +* [What the public spec contains](#what-the-public-spec-contains) +* [What the public spec does not contain](#what-the-public-spec-does-not-contain) +* [Endpoint-level authentication is unchanged](#endpoint-level-authentication-is-unchanged) +* [ASVS reference](#asvs-reference) +* [Implementation references](#implementation-references) + +## Overview + +ATR publishes machine-readable API documentation at two endpoints: + +* `/api/openapi.json` — the OpenAPI 3 specification for the ATR HTTP API +* `/api/docs` — a Swagger UI rendering of that specification + +Both endpoints are reachable without authentication. This document records the reason that is the intended behaviour, what the public surface does and does not include, and what protections are in place at the endpoints the specification describes. + +## Decision + +`/api/openapi.json` and `/api/docs` are **intentionally public** and do not require authentication. The corresponding inline `audit_guidance` comment in [`atr/server.py`](/ref/atr/server.py) is the source of truth for the implementation; this page is the policy record. + +## Rationale + +1. **ATR exposes a public API by design.** The HTTP API is consumed by the `atr` CLI client, by ASF tooling GitHub Actions, and by other release tooling outside the ASF. Publishing the specification publicly is the most direct way for those clients, and for prospective contributors, to discover what the API offers. + +2. **Open-source ASF practice.** ATR is an Apache Software Foundation project. Project interfaces and their documentation are expected to be openly accessible. + +3. **No admin or internal surface is exposed.** The `ApiOnlyOpenAPIProvider` class in [`atr/server.py`](/ref/atr/server.py) filters the generated specification so that only routes whose path begins with `/api` appear. Admin routes, internal blueprints, and the web UI's own endpoints are excluded from the published spec, so an unauthenticated reader does not learn about them from this channel. + +4. **Documenting an endpoint does not grant access to it.** The `@quart_schema.hide` decorator on the Swagger UI route only suppresses that route from appearing in the spec; it does not relax the rate limit, the CSRF posture, or any per-endpoint authentication check. Authentication for the documented API is enforced separately, at the endpoint, as described below. + +## What the public spec contains + +* Paths under `/api` +* HTTP methods, parameter names and types, request body schemas, and response schemas for those paths +* The `BearerAuth` security scheme declaration, so that clients know JWT Bearer tokens are the expected credential for protected operations Review Comment: Probably should mention all of our auth levels. Public endpoints require no credential, bearer endpoints require ATR issued JWTs from PATs, trusted-publisher endpoints require validated OIDC body credentials, and /api/jwt/create accepts a PAT to issue JWTs. -- 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] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
