diff --git a/README.md b/README.md index a899461..de09ee2 100644 --- a/README.md +++ b/README.md @@ -70,13 +70,13 @@ TOKEN_ENCRYPTION_KEY=your-generated-key-here Open `http://localhost:8000` in your browser. On first boot, Firebreak redirects to a setup wizard where you configure: -- **Forgejo instance URL** — where your Forgejo server lives +- **Forgejo instance URL** — use HTTPS unless Forgejo is a local service or loopback endpoint - **OAuth credentials** — register an OAuth application in Forgejo first (Settings → Applications → Create OAuth2 Application), then paste the Client ID and Client Secret - **Public base URL** (optional) — your production domain for OAuth redirects ### 4. Sign In and Register Your Token -After setup, sign in with your Forgejo account via OAuth. On first login, Firebreak prompts you to register a `read:repository`-scoped personal access token (PAT) so you can browse your repositories and preview snapshots. +After setup, sign in with your Forgejo account via OAuth. Register a personal access token (PAT) with `read:user` and `read:repository` so you can browse your repositories and preview snapshots. See the [Firebreak glossary](docs/glossary.md) for the difference between snapshots, share links, and grants. diff --git a/agents.md b/agents.md index 7ff9e61..6543ea5 100644 --- a/agents.md +++ b/agents.md @@ -129,9 +129,9 @@ This file is the single source of truth for codebase obstacles, oddities, and th **Preference:** A valid token alone is insufficient for repository-access verification. ### Forgejo PAT could be sent over remote HTTP -**Area:** cli/src/utils/forgejo-checks.ts, cli/src/commands/config/init.ts -**Obstacle:** CLI setup and verification accepted remote `http://` Forgejo URLs, allowing the PAT to be sent without transport encryption. -**Solution/Workaround:** Centralize Forgejo URL validation, require HTTPS for non-local endpoints, and allow HTTP only for the documented `forgejo` service and loopback hosts. Validate again inside authenticated checks before constructing requests. +**Area:** cli/src/utils/forgejo-checks.ts, cli/src/commands/config/init.ts, web/app/clients/forgejo.py +**Obstacle:** Accepting remote `http://` Forgejo URLs allowed credentials to be sent without transport encryption. +**Solution/Workaround:** Require HTTPS for non-local endpoints and allow HTTP only for the documented `forgejo` service and loopback hosts. Validate at each client boundary before sending credentials. **Preference:** Reject insecure remote transport instead of adding an acknowledgement flag. ### Tailwind standalone CLI was killed by macOS code signing @@ -247,3 +247,21 @@ This file is the single source of truth for codebase obstacles, oddities, and th **Obstacle:** djLint H020 flags the empty element even though the browser fills it from the selected option. **Solution/Workaround:** Suppress H020 in the picker fragment and leave its native select markup intact. **Preference:** Keep customizable-select styling behind feature queries, with the native picker as the fallback. + +### Forgejo owned repository listing requires two PAT scopes +**Area:** web/app/clients/forgejo.py, web/app/templates/settings.html +**Obstacle:** Forgejo's `/users/{username}/repos` requires `read:user` and `read:repository`; a PAT with only `read:repository` cannot populate the dashboard or picker. +**Solution/Workaround:** Name both scopes in setup guidance and the client error for a rejected token. +**Preference:** Keep the owner-specific listing and its pagination metadata. + +### Unqualified branch names can resolve to a tag +**Area:** web/app/routers/repositories.py, web/app/clients/forgejo.py +**Obstacle:** Forgejo's commits listing accepts a general Git ref; a tag and branch can have the same name. +**Solution/Workaround:** Resolve the exact branch with Forgejo's branch endpoint once, then use its tip SHA for every commit page in the picker. +**Preference:** Leave the JSON commits endpoint's branch/tag/SHA contract unchanged. + +### Malformed Forgejo payloads bypassed inline errors +**Area:** web/app/clients/forgejo.py +**Obstacle:** Non-JSON responses or invalid JSON shapes raised outside the dashboard/picker's HTTP error boundary. Pydantic v2 also lets a validator's `TypeError` escape validation. +**Solution/Workaround:** Validate expected JSON shapes in the client, use `ValueError` for field validation, and return a sanitized 502 for malformed data. +**Preference:** Keep the dashboard and picker usable without displaying upstream response content. diff --git a/web/app/clients/forgejo.py b/web/app/clients/forgejo.py index cf5dc9d..25fd926 100644 --- a/web/app/clients/forgejo.py +++ b/web/app/clients/forgejo.py @@ -7,10 +7,47 @@ from urllib.parse import quote import httpx from fastapi import HTTPException, status -from pydantic import AliasChoices, AliasPath, BaseModel, Field, field_validator +from pydantic import ( + AliasChoices, + AliasPath, + BaseModel, + Field, + TypeAdapter, + ValidationError, + field_validator, +) from app.models.app_settings import AppSettings +_LOCAL_HTTP_HOSTS = {"localhost", "127.0.0.1", "::1", "forgejo"} + + +def _authenticated_base_url(value: str) -> httpx.URL: + """Require encrypted transport except for documented local Forgejo hosts.""" + try: + url = httpx.URL(value.strip()) + except httpx.InvalidURL: + raise HTTPException( + status_code=status.HTTP_503_SERVICE_UNAVAILABLE, + detail="Configure a valid Forgejo URL in setup.", + ) from None + + local_http = url.scheme == "http" and ( + url.host in _LOCAL_HTTP_HOSTS or url.host.endswith(".localhost") + ) + if ( + not url.host + or (url.scheme != "https" and not local_http) + or url.userinfo + or url.query + or url.fragment + ): + raise HTTPException( + status_code=status.HTTP_503_SERVICE_UNAVAILABLE, + detail="Configure an HTTPS Forgejo URL in setup. HTTP is only allowed for local Forgejo endpoints.", + ) + return url + class Repo(BaseModel): """A repository returned by Forgejo.""" @@ -31,7 +68,7 @@ class Repo(BaseModel): @classmethod def map_visibility(cls, value: Any) -> Literal["private", "public"]: if not isinstance(value, bool): - raise TypeError(f"expected a boolean, got {value!r}") + raise ValueError("expected a boolean") # noqa: TRY004 return "private" if value else "public" @@ -51,7 +88,10 @@ class Commit(BaseModel): accepts either shape. """ - id: str = Field(validation_alias=AliasChoices("sha", "id")) + id: str = Field( + validation_alias=AliasChoices("sha", "id"), + pattern=r"^(?:[a-f0-9]{40}|[a-f0-9]{64})$", + ) message: str = Field( validation_alias=AliasChoices("message", AliasPath("commit", "message")) ) @@ -74,6 +114,27 @@ class Branch(BaseModel): commit: Commit +_REPOSITORIES = TypeAdapter(list[Repo]) +_BRANCHES = TypeAdapter(list[Branch]) +_BRANCH = TypeAdapter(Branch) +_COMMITS = TypeAdapter(list[Commit]) +_OBJECT = TypeAdapter(dict[str, Any]) + + +def _malformed_response() -> HTTPException: + return HTTPException( + status_code=status.HTTP_502_BAD_GATEWAY, + detail="Forgejo returned unexpected data. Check the Forgejo URL and try again.", + ) + + +def _parse_json[T](response: httpx.Response, adapter: TypeAdapter[T]) -> T: + try: + return adapter.validate_json(response.content) + except ValidationError: + raise _malformed_response() from None + + async def get_repos( app_settings: AppSettings, access_token: str, @@ -101,29 +162,8 @@ async def get_repos( params: dict[str, str | int] = {"limit": limit, "page": page} endpoint = f"/users/{quote(owner, safe='')}/repos" if owner else "/user/repos" path = f"/api/v1{endpoint}?{httpx.QueryParams(params)}" - try: - async with httpx.AsyncClient( - base_url=app_settings.forgejo_base_url, timeout=30.0 - ) as client: - response = await client.get( - path, headers={"Authorization": f"token {access_token}"} - ) - except httpx.RequestError: - raise HTTPException( - status_code=status.HTTP_502_BAD_GATEWAY, - detail="Cannot reach Forgejo. Check your connection settings.", - ) - if response.status_code in {401, 403}: - raise HTTPException( - status_code=status.HTTP_502_BAD_GATEWAY, - detail="Forgejo rejected your access token. Check its permissions or replace it in settings.", - ) - if response.status_code != 200: - raise HTTPException( - status_code=status.HTTP_502_BAD_GATEWAY, - detail=f"Forgejo could not load repositories ({response.status_code}). Try again later.", - ) - repos = [Repo.model_validate(repo) for repo in response.json()] + response = await _get(app_settings, path, access_token) + repos = _parse_json(response, _REPOSITORIES) total_count_header = response.headers.get("x-total-count") try: total_count = int(total_count_header) if total_count_header else None @@ -156,15 +196,29 @@ async def get_branches( A list of branches. """ - branches = await get( + response = await _get( app_settings, f"/api/v1/repos/{quote(owner, safe='')}/{quote(repo, safe='')}/branches?" f"{httpx.QueryParams({'limit': limit, 'page': page})}", access_token, ) - if not branches: - return [] - return [Branch.model_validate(b) for b in branches] + return _parse_json(response, _BRANCHES) + + +async def get_branch_tip( + app_settings: AppSettings, access_token: str, owner: str, repo: str, branch: str +) -> str: + """Resolve a branch by name without letting Git choose a tag or other ref.""" + response = await _get( + app_settings, + f"/api/v1/repos/{quote(owner, safe='')}/{quote(repo, safe='')}" + f"/branches/{quote(branch, safe='')}", + access_token, + ) + result = _parse_json(response, _BRANCH) + if result.name != branch: + raise _malformed_response() + return result.commit.id async def get_commits( @@ -190,15 +244,13 @@ async def get_commits( Returns: A list of commits. """ - commits = await get( + response = await _get( app_settings, f"/api/v1/repos/{quote(owner, safe='')}/{quote(repo, safe='')}/commits?" f"{httpx.QueryParams({'sha': ref, 'limit': limit, 'page': page})}", access_token, ) - if not commits: - return [] - return [Commit.model_validate(c) for c in commits] + return _parse_json(response, _COMMITS) async def post(app_settings: AppSettings, path: str, data: dict) -> dict: @@ -212,10 +264,9 @@ async def post(app_settings: AppSettings, path: str, data: dict) -> dict: Returns: The response from the Forgejo API. """ + base_url = _authenticated_base_url(app_settings.forgejo_base_url) try: - async with httpx.AsyncClient( - base_url=app_settings.forgejo_base_url, timeout=30.0 - ) as client: + async with httpx.AsyncClient(base_url=base_url, timeout=30.0) as client: resp = await client.post( path, data=data, headers={"Accept": "application/json"} ) @@ -229,26 +280,23 @@ async def post(app_settings: AppSettings, path: str, data: dict) -> dict: status_code=status.HTTP_502_BAD_GATEWAY, detail=f"Forgejo returned an error ({resp.status_code}). Verify your OAuth configuration.", ) - return resp.json() + return _parse_json(resp, _OBJECT) async def get( app_settings: AppSettings, path: str, access_token: str -) -> dict | list[dict]: - """Send a GET request to the Forgejo API. +) -> dict[str, Any]: + """Fetch a JSON object from the Forgejo API.""" + return _parse_json(await _get(app_settings, path, access_token), _OBJECT) - Args: - app_settings: The application settings. - path: The path to the Forgejo API endpoint. - access_token: The authentication token. - Returns: - The response from the Forgejo API as a dictionary or list of dictionaries. - """ +async def _get( + app_settings: AppSettings, path: str, access_token: str +) -> httpx.Response: + """Fetch a response without dropping headers needed for pagination.""" + base_url = _authenticated_base_url(app_settings.forgejo_base_url) try: - async with httpx.AsyncClient( - base_url=app_settings.forgejo_base_url, timeout=30.0 - ) as client: + async with httpx.AsyncClient(base_url=base_url, timeout=30.0) as client: resp = await client.get( path, headers={"Authorization": f"token {access_token}"} ) @@ -257,9 +305,14 @@ async def get( status_code=status.HTTP_502_BAD_GATEWAY, detail="Cannot reach Forgejo. Check your connection settings.", ) - if resp.status_code != 200: - raise HTTPException( - status_code=status.HTTP_502_BAD_GATEWAY, - detail=f"Forgejo returned an error ({resp.status_code}). Verify your OAuth configuration.", + if resp.status_code == 200: + return resp + if resp.status_code in {401, 403}: + detail = ( + "Forgejo rejected the access token. For repository browsing, " + "check that your personal access token is valid and has " + "read:user and read:repository scopes." ) - return resp.json() + else: + detail = f"Forgejo returned an error ({resp.status_code}). Check the connection settings and try again." + raise HTTPException(status_code=status.HTTP_502_BAD_GATEWAY, detail=detail) diff --git a/web/app/routers/repositories.py b/web/app/routers/repositories.py index aa32679..65b3c7f 100644 --- a/web/app/routers/repositories.py +++ b/web/app/routers/repositories.py @@ -216,6 +216,8 @@ async def _snapshot_options( ref: str, ) -> list[tuple[str, str]]: options: list[tuple[str, str]] = [] + if step == "commit": + ref = await forgejo.get_branch_tip(app_settings, access_token, owner, repo, ref) for page in count(1): if step == "repository": result = await forgejo.get_repos( diff --git a/web/app/templates/settings.html b/web/app/templates/settings.html index a347b7a..af0998d 100644 --- a/web/app/templates/settings.html +++ b/web/app/templates/settings.html @@ -13,8 +13,10 @@

Forgejo access token

- A read:repository-scoped - personal access token lets Firebreak browse your repositories and preview snapshots. + Use a personal access token with + read:user + and read:repository + to browse your repositories and preview snapshots.

{% if pat_registered %}