Compare commits

..

4 commits

12 changed files with 854 additions and 75 deletions

View file

@ -70,13 +70,15 @@ 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) to enable share link viewing.
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.
### 5. Alternative Deployments

View file

@ -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
@ -199,3 +199,69 @@ This file is the single source of truth for codebase obstacles, oddities, and th
**Obstacle:** Calculating the next page from the requested limit stops pagination early when Forgejo's configured page-size cap is lower.
**Solution/Workaround:** Preserve the `next` relation from Forgejo's `Link` header as `RepoPage.has_next_page` and use it directly on the dashboard.
**Preference:** Use upstream pagination links rather than assuming the requested page size was honored.
### Picker listing endpoints omit pagination metadata
**Area:** web/app/routers/repositories.py, web/app/templates/snapshot_picker.html
**Obstacle:** Branch and commit client helpers return plain lists; a short page cannot prove there are no further results because Forgejo may cap page sizes.
**Solution/Workaround:** The picker-specific HTML route follows repository pagination metadata and walks branch pages until empty. Commit requests stop at an empty page or 30 recent commits. JSON listing responses are unchanged.
**Preference:** Paginate automatically without guessing from page length or changing existing API consumers.
### Branch refs need URL query encoding
**Area:** web/app/clients/forgejo.py
**Obstacle:** Interpolating a branch ref into the Forgejo commits query can corrupt names containing characters such as `&` or `#`.
**Solution/Workaround:** Build query strings with `httpx.QueryParams` and quote owner and repository path components.
**Preference:** Encode URL components at the HTTP client boundary.
### Duplicate element IDs silently broke the snapshot picker
**Area:** web/app/templates/dashboard.html, web/app/static/js/snapshot-picker.js
**Obstacle:** The selected-snapshot summary cells reused `snapshot-branch` and `snapshot-commit`, colliding with the picker's `<select>` IDs. `getElementById` returned the hidden summary cell, so `closest(".picker-step")` was `null` and the click handler threw before `showModal()` — the dialog never opened and no visible error appeared.
**Solution/Workaround:** Prefix summary IDs with `snapshot-selected-` and check the rendered template for duplicate IDs.
**Preference:** Keep picker control IDs and display IDs distinct; treat a dialog that fails to open as a JavaScript error first and check the console.
### Appending picker options can change the selected value
**Area:** web/app/templates/snapshot_picker.html
**Obstacle:** A temporary `<select>` wrapper auto-selects its first option before HTMX moves it into the live select, overriding the user's choice.
**Solution/Workaround:** The old paginated UI appended through an inert `<template>` with a neutral wrapper. The current picker renders complete option sets and no longer appends options.
**Preference:** Avoid swapping from a temporary `<select>` when appending to a live one.
### Cached snapshot script broke the new dialog markup
**Area:** web/app/templates/dashboard.html, web/app/static/js/snapshot-picker.js
**Obstacle:** During the HTMX migration, the browser could reuse the old picker script against the new HTML and fail before opening the dialog.
**Solution/Workaround:** The script URL was versioned during the migration. The current picker uses native dialog commands and no longer includes a custom script.
**Preference:** Keep the HTML and its script in sync without requiring users to hard-refresh.
### Forgejo commit listing has no message search
**Area:** web/app/routers/repositories.py, web/app/templates/snapshot_picker.html
**Obstacle:** Filtering just the first page misses commits; scanning an entire branch on each search can slow large repositories.
**Solution/Workaround:** The picker previously filtered up to 100 commits by message or SHA prefix. At the user's request, it now only lists up to 30 recent commits in the dropdown.
**Preference:** Keep the picker dropdown-only; don't scan the entire commit history.
### Snapshot picker changes shifted the modal frame
**Area:** web/app/static/css/input.css, web/app/templates/dashboard.html
**Obstacle:** The dialog only had a maximum height, HTMX loading removed fields from layout, and locking root overflow could remove the page scrollbar.
**Solution/Workaround:** Use a viewport-capped fixed dialog size, a scrolling body with a stable scrollbar gutter, and a grid overlay for loading. Contain scroll chaining on the dialog and its backdrop rather than changing root overflow.
**Preference:** Keep the shell and field space stable without JavaScript.
### djLint reports empty native selectedcontent as an error
**Area:** web/app/templates/snapshot_picker.html
**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.

11
docs/glossary.md Normal file
View file

@ -0,0 +1,11 @@
# Firebreak glossary
A **share link** opens a **snapshot**. A **grant** is the internal record Firebreak checks to decide whether to allow access.
| Term | Meaning | Where it belongs |
| --- | --- | --- |
| **Snapshot** | A repository's content at a specific commit SHA. The branch helps users find a commit; it does not change what a link opens later. | Picker, preview, and viewer copy. A snapshot doesn't need a separate database model. |
| **Share link** | The URL someone copies and sends to let others view a snapshot. | Dashboard copy, share-link API names, and `/links` routes for creating and managing links. |
| **Grant** | The stored access record: the repository and commit SHA, expiration, revocation, and any recipient restriction. | The `Grant` model, `grants` table, and backend authorization code. Use **share link**, not **grant**, in user-facing copy. |
The dashboard's snapshot picker lives under `/dashboard/snapshot-picker`. Selecting or clearing a preview does not create, publish, or revoke a share link. Existing JSON repository listings stay under `/links/repositories` for compatibility.

View file

@ -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,14 +196,29 @@ async def get_branches(
A list of branches.
"""
branches = await get(
response = await _get(
app_settings,
f"/api/v1/repos/{owner}/{repo}/branches?limit={limit}&page={page}",
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(
@ -189,14 +244,13 @@ async def get_commits(
Returns:
A list of commits.
"""
commits = await get(
response = await _get(
app_settings,
f"/api/v1/repos/{owner}/{repo}/commits?sha={ref}&limit={limit}&page={page}",
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:
@ -210,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"}
)
@ -227,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}"}
)
@ -255,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)

View file

@ -91,6 +91,7 @@ app.mount(
app.include_router(auth.router)
app.include_router(links.router)
app.include_router(repositories.router)
app.include_router(repositories.picker_router)
app.include_router(settings.router)
app.include_router(setup.router)

View file

@ -1,6 +1,8 @@
from typing import Annotated
from itertools import count
from typing import Annotated, Literal
from fastapi import APIRouter, Depends, HTTPException, Path, Query, status
from fastapi import APIRouter, Depends, HTTPException, Path, Query, Request, status
from fastapi.responses import HTMLResponse, Response
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
@ -12,8 +14,10 @@ from app.models.app_settings import AppSettings
from app.models.session import Session as UserBrowserSession
from app.models.user import LinkedIdentity
from app.settings import get_app_settings, get_fernet
from app.templating import templates
router = APIRouter(prefix="/links", tags=["repositories"])
picker_router = APIRouter(prefix="/dashboard/snapshot-picker", include_in_schema=False)
async def get_forgejo_token(
@ -122,3 +126,137 @@ async def get_repository_commits(
app_settings, access_token, owner, repo, ref=ref, limit=limit, page=page
)
return commits
RECENT_COMMITS = 30
PICKER_PAGE_SIZE = 50
@picker_router.get("/preview", response_class=HTMLResponse)
async def preview_snapshot(
request: Request,
_session: Annotated[UserBrowserSession, Depends(get_current_session)],
repo: Annotated[str, Query(max_length=255)] = "",
ref: Annotated[str, Query(max_length=1024)] = "",
commit: Annotated[str, Query(pattern=r"^(?:[a-f0-9]{40}|[a-f0-9]{64})?$")] = "",
) -> Response:
"""Render a display-only preview, or clear it when no snapshot is supplied."""
confirmed = bool(repo and ref and commit)
return templates.TemplateResponse(
request,
"snapshot_preview.html",
{"repo": repo, "ref": ref, "commit": commit, "confirmed": confirmed},
headers={"Cache-Control": "no-store"},
block_name="preview_confirmation" if confirmed else "selected_snapshot",
)
@picker_router.get("/{step}", response_class=HTMLResponse)
async def get_snapshot_picker_step(
request: Request,
step: Literal["repository", "branch", "commit"],
app_settings: Annotated[AppSettings, Depends(get_app_settings)],
session: Annotated[UserBrowserSession, Depends(get_current_session)],
db: Annotated[AsyncSession, Depends(get_db)],
repo: Annotated[str, Query(max_length=255)] = "",
ref: Annotated[str, Query(max_length=1024)] = "",
) -> Response:
"""Load dependent picker options without changing the JSON listing API."""
if step != "repository" and (repo in {".", ".."} or "/" in repo or "\\" in repo):
raise HTTPException(status_code=400, detail="Invalid repository name.")
options: list[tuple[str, str]] = []
error = False
message = ""
try:
if step == "repository" or (repo and (step == "branch" or ref)):
access_token = await get_forgejo_token(session)
owner = await get_forgejo_owner(session, db)
options = await _snapshot_options(
step, app_settings, access_token, owner, repo, ref
)
if not options:
message = {
"repository": "No repositories found.",
"branch": "No branches found.",
"commit": "No commits found.",
}[step]
except HTTPException as exc:
if exc.status_code not in {403, 502, 503}:
raise
error = True
message = str(exc.detail)
return templates.TemplateResponse(
request,
"snapshot_picker.html",
{
"step": step,
"options": options,
"message": message,
"error": error,
"repo": repo,
"ref": ref,
},
headers={"Cache-Control": "no-store"},
block_name={
"repository": "picker_steps",
"branch": "branch_steps",
"commit": "commit_step",
}[step],
)
async def _snapshot_options(
step: Literal["repository", "branch", "commit"],
app_settings: AppSettings,
access_token: str,
owner: str,
repo: str,
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(
app_settings,
access_token,
owner=owner,
page=page,
limit=PICKER_PAGE_SIZE,
)
options.extend((item.repo_name, item.repo_name) for item in result.repos)
if not result.has_next_page or not result.repos:
break
elif step == "branch":
branches = await forgejo.get_branches(
app_settings,
access_token,
owner,
repo,
page=page,
limit=PICKER_PAGE_SIZE,
)
if not branches:
break
options.extend((item.name, item.name) for item in branches)
else:
commits = await forgejo.get_commits(
app_settings,
access_token,
owner,
repo,
ref=ref,
page=page,
limit=RECENT_COMMITS,
)
if not commits:
break
for item in commits[: RECENT_COMMITS - len(options)]:
subject = item.message.partition("\n")[0]
options.append((item.id, f"{item.id[:7]} — {subject}"))
if len(options) == RECENT_COMMITS:
break
return options

View file

@ -275,6 +275,289 @@
.input-error {
@apply text-sm font-medium text-danger-foreground;
}
.snapshot-grid {
display: grid;
gap: 1px;
background: var(--color-border);
}
.snapshot-cell {
padding: 0.75rem 1.25rem;
background: var(--color-card);
}
.snapshot-value {
margin-top: 0.25rem;
font-family: var(--font-mono);
font-size: 0.75rem;
line-height: 1.5;
color: var(--color-foreground);
overflow-wrap: anywhere;
}
@media (min-width: 640px) {
.snapshot-grid {
grid-template-columns: repeat(3, minmax(0, 1fr));
}
}
.picker-dialog {
inline-size: min(34rem, calc(100dvw - 2rem));
block-size: min(37rem, calc(100dvh - 2rem));
max-inline-size: none;
max-block-size: none;
margin: auto;
padding: 0;
overflow: hidden;
overscroll-behavior: contain;
border: 1px solid var(--color-border);
border-radius: var(--radius-xl);
background: var(--color-card);
color: var(--color-card-foreground);
box-shadow: 0 24px 64px rgb(0 0 0 / 55%);
}
.picker-dialog::backdrop {
background: rgb(0 0 0 / 72%);
overflow: hidden;
overscroll-behavior: contain;
}
.picker-layout {
display: grid;
grid-template-rows: auto minmax(0, 1fr);
block-size: 100%;
}
.picker-header {
display: flex;
align-items: flex-start;
justify-content: space-between;
gap: 1rem;
padding: 1.25rem 1.5rem 1rem;
border-bottom: 1px solid var(--color-border);
background: var(--color-card);
}
.picker-title {
font-size: 1rem;
font-weight: 600;
}
.picker-description {
max-width: 42ch;
margin-top: 0.25rem;
font-size: 0.8125rem;
line-height: 1.45;
color: var(--color-muted-foreground);
}
.picker-close {
display: grid;
flex-shrink: 0;
place-items: center;
width: 2rem;
height: 2rem;
border: 1px solid transparent;
border-radius: var(--radius-md);
color: var(--color-muted-foreground);
transition: background-color 120ms ease, color 120ms ease;
}
.picker-close:hover {
background: var(--color-muted);
color: var(--color-foreground);
}
.picker-loaded {
display: flex;
flex-direction: column;
gap: 1rem;
}
.picker-steps {
padding: 1.25rem 1.5rem 1.5rem;
overflow: auto;
overscroll-behavior: contain;
scrollbar-gutter: stable;
}
.picker-step {
display: grid;
grid-template-columns: 1.5rem minmax(0, 1fr);
gap: 0.875rem;
}
.picker-step-index {
display: grid;
place-items: center;
width: 1.5rem;
height: 1.5rem;
margin-top: 0.125rem;
border: 1px solid var(--color-border);
border-radius: 9999px;
background: var(--color-muted);
font-family: var(--font-mono);
font-size: 0.6875rem;
color: var(--color-muted-foreground);
transition: border-color 120ms ease, background-color 120ms ease,
color 120ms ease;
}
.picker-step:has(select:required:valid:not(:disabled)) > .picker-step-index {
border-color: var(--color-success);
background: var(--color-success-muted);
color: var(--color-success-foreground);
}
.picker-step-label {
display: block;
font-size: 0.75rem;
font-weight: 600;
color: var(--color-muted-foreground);
}
.picker-select {
inline-size: 100%;
min-inline-size: 0;
min-height: 2.75rem;
margin-top: 0.5rem;
padding: 0.625rem 0.875rem;
border: 1px solid var(--color-border);
border-radius: var(--radius-lg);
background: var(--color-input);
color-scheme: dark;
font-family: var(--font-sans);
font-size: 0.875rem;
line-height: 1.5;
color: var(--color-foreground);
text-overflow: ellipsis;
transition: border-color 120ms ease, background-color 120ms ease;
}
.picker-select:hover:not(:disabled) {
border-color: var(--color-muted-foreground);
background: var(--color-muted);
}
.picker-select option {
background: var(--color-card);
color: var(--color-card-foreground);
}
.picker-select:focus-visible {
border-color: var(--color-ring);
outline: none;
box-shadow: 0 0 0 3px var(--color-ring-muted);
}
.picker-select:disabled {
cursor: not-allowed;
opacity: 0.45;
}
@supports (appearance: base-select) and selector(select::picker(select)) {
select.picker-select,
select.picker-select::picker(select) {
appearance: base-select;
}
select.picker-select > button {
flex: 1;
min-inline-size: 0;
text-align: start;
}
select.picker-select selectedcontent {
display: block;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
select.picker-select::picker-icon {
flex: none;
margin-inline-start: auto;
padding-inline-start: 0.625rem;
color: var(--color-muted-foreground);
line-height: 1;
}
select.picker-select::picker(select) {
max-block-size: min(16rem, calc(50dvh - 2rem));
overflow: auto;
overscroll-behavior: contain;
border: 1px solid var(--color-border);
border-radius: var(--radius-lg);
background: var(--color-card);
color: var(--color-card-foreground);
box-shadow: 0 8px 24px rgb(0 0 0 / 35%);
}
select.picker-select option {
padding: 0.5rem 0.875rem;
overflow-wrap: anywhere;
white-space: normal;
}
select.picker-select option:is(:hover, :focus-visible, :checked) {
background: var(--color-muted);
}
@supports (position-area: block-end) and (inline-size: anchor-size(inline)) {
select.picker-select::picker(select) {
inset: auto;
margin: 0.25rem 0;
position-area: block-end;
position-try-fallbacks: flip-block;
inline-size: anchor-size(inline);
min-inline-size: 0;
}
}
}
.picker-status {
margin-top: 0.375rem;
font-size: 0.75rem;
line-height: 1.25rem;
color: var(--color-muted-foreground);
}
.picker-status[data-state="error"] {
color: var(--color-danger-foreground);
}
.picker-load-scope {
display: grid;
grid-template-columns: minmax(0, 1fr);
align-content: start;
}
.picker-load-scope > :is(.picker-loading, .picker-loaded) {
grid-area: 1 / 1;
}
.picker-loading,
.picker-load-scope.htmx-request > .picker-loaded {
visibility: hidden;
}
.picker-load-scope.htmx-request > .picker-loading {
visibility: visible;
}
.picker-close:focus-visible {
outline: 2px solid var(--color-ring);
outline-offset: 2px;
}
.picker-actions {
display: flex;
justify-content: flex-end;
gap: 0.5rem;
margin-top: 1rem;
}
}
@ -289,4 +572,4 @@
height: auto; /* Maintains aspect ratio */
display: block; /* Removes bottom whitespace common in inline images */
}
}
}

View file

@ -8,22 +8,70 @@
<p class=" text-2xl text-muted-foreground">{{ user.display_name or user.email }}.</p>
</div>
{% if pat_registered %}
<a href="/links/create" class="btn btn-primary w-fit">Create share link</a>
<button type="button"
id="open-snapshot-picker"
class="btn btn-primary w-fit"
commandfor="snapshot-picker"
command="show-modal"
hx-get="{{ url_for('get_snapshot_picker_step', step='repository').path }}"
hx-target="#snapshot-picker-body"
hx-swap="innerHTML"
hx-indicator="#snapshot-picker-scope"
hx-sync="#snapshot-picker:replace">Select snapshot</button>
{% else %}
<span class="btn btn-primary w-fit opacity-50 pointer-events-none"
aria-disabled="true">Create share link</span>
aria-disabled="true">Select snapshot</span>
{% endif %}
</section>
{% if pat_registered %}
{% include "snapshot_preview.html" %}
<dialog id="snapshot-picker"
class="picker-dialog"
aria-labelledby="snapshot-title"
aria-describedby="snapshot-description">
<div class="picker-layout">
<header class="picker-header">
<div>
<h2 id="snapshot-title" class="picker-title">Select a snapshot</h2>
<p id="snapshot-description" class="picker-description">
Choose a repository, then a branch and commit. This previews a snapshot without creating a share link.
</p>
</div>
<button type="button"
class="picker-close"
aria-label="Close dialog"
commandfor="snapshot-picker"
command="close">
<svg width="16"
height="16"
viewBox="0 0 16 16"
fill="none"
stroke="currentColor"
stroke-width="1.5"
aria-hidden="true">
<path d="M4 4l8 8M12 4l-8 8" stroke-linecap="round" />
</svg>
</button>
</header>
<div id="snapshot-picker-scope" class="picker-steps picker-load-scope">
<p class="picker-status picker-loading" role="status">Loading selection…</p>
<div id="snapshot-picker-body" class="picker-loaded">
<p class="picker-status" role="status">Could not load repositories. Close the picker and try again.</p>
</div>
</div>
</div>
</dialog>
{% endif %}
<section class="grid gap-4 md:grid-cols-3">
<div class="p-4 card">
<p class="section-header-subtle">Active links</p>
<p class="section-header-subtle">Active share links</p>
<p class="mt-3 text-2xl font-semibold text-foreground">0</p>
<p class="mt-2 text-xs text-muted-foreground">No repository snapshots published yet.</p>
<p class="mt-2 text-xs text-muted-foreground">No active share links yet.</p>
</div>
<div class="p-4 card">
<p class="section-header-subtle">Default expiry</p>
<p class="mt-3 text-2xl font-semibold text-foreground">7 days</p>
<p class="mt-2 text-xs text-muted-foreground">Applied to newly created links.</p>
<p class="mt-2 text-xs text-muted-foreground">Applied to newly created share links.</p>
</div>
<div class="p-4 card">
<p class="section-header-subtle">Audit events</p>
@ -35,7 +83,7 @@
<div class="rounded-lg border border-warning-muted bg-warning-muted/40 px-5 py-4">
<p class="text-sm font-semibold text-warning-foreground">Access token required</p>
<p class="mt-1 text-sm text-muted-foreground">
Register a Forgejo access token to create share links.
Register a Forgejo access token to browse repositories and select a snapshot.
</p>
<a href="/settings" class="btn btn-sm btn-primary mt-3 w-fit">Go to Settings</a>
</div>
@ -43,7 +91,7 @@
<div class="space-y-3">
<div>
<h2 class="text-base font-semibold">Share links</h2>
<p class="mt-2 text-sm text-muted-foreground">Repository snapshots published from this account.</p>
<p class="mt-2 text-sm text-muted-foreground">Share links you’ve created.</p>
</div>
<section class="card">
<div class="overflow-x-auto">

View file

@ -28,7 +28,7 @@
<span class="mt-2 block">Draw a boundary around your code. Let them look, but don't let them scrape.</span>
</p>
<p class="mt-7 max-w-xl rounded-lg border border-[#f7f2e8]/14 bg-[#17191c]/42 px-5 py-4 text-sm leading-6 text-[#f7f2e8]/76 shadow-[0_18px_50px_rgb(0_0_0_/0.24)] backdrop-blur-sm sm:text-[0.9375rem]">
Firebreak creates temporary, read-only links to private Forgejo repository snapshots.
Firebreak is designed for sharing read-only snapshots of private Forgejo repositories through temporary share links.
Sign in using Forgejo, register an access token, and control what can be viewed and by whom.
</p>
<div class="mt-7 flex flex-wrap items-center justify-center gap-3">

View file

@ -13,8 +13,10 @@
<div id="forgejo-access-token">
<h2 class="text-base font-semibold">Forgejo access token</h2>
<p class="mt-2 text-sm text-muted-foreground">
A <code class="rounded-sm bg-secondary px-1.5 py-0.5 text-foreground">read:repository</code>-scoped
Personal Access Token is required for share link viewing.
Use a personal access token with
<code class="rounded-sm bg-secondary px-1.5 py-0.5 text-foreground">read:user</code>
and <code class="rounded-sm bg-secondary px-1.5 py-0.5 text-foreground">read:repository</code>
to browse your repositories and preview snapshots.
</p>
{% if pat_registered %}
<div class="mt-4 card">

View file

@ -0,0 +1,125 @@
{# The browser fills selectedcontent when a native select option is chosen. #}
<!-- djlint:off H020 -->
{% block picker_steps %}
<div class="picker-step">
<span class="picker-step-index" aria-hidden="true">1</span>
<div>
<label for="snapshot-repository" class="picker-step-label">Repository</label>
<select id="snapshot-repository"
class="picker-select"
name="repo"
required
{% if not options %}disabled{% endif %}
hx-get="{{ url_for('get_snapshot_picker_step', step='branch').path }}"
hx-trigger="change"
hx-target="#snapshot-branch-content"
hx-swap="innerHTML"
hx-indicator="#snapshot-branch-scope"
hx-sync="#snapshot-picker:replace">
<button type="button"><selectedcontent></selectedcontent></button>
<option value="">Choose a repository</option>
{% for value, label in options %}<option value="{{ value }}">{{ label }}</option>{% endfor %}
</select>
<p class="picker-status" role="status" {% if error %}data-state="error"{% endif %}>{{ message }}</p>
</div>
</div>
<div id="snapshot-branch-scope" class="picker-load-scope">
<p class="picker-status picker-loading" role="status">Loading branches…</p>
<div id="snapshot-branch-content" class="picker-loaded">
{% block branch_steps %}
<div class="picker-step">
<span class="picker-step-index" aria-hidden="true">2</span>
<div>
<label for="snapshot-branch" class="picker-step-label">Branch</label>
<select id="snapshot-branch"
class="picker-select"
name="ref"
required
{% if step != "branch" or not options %}disabled{% endif %}
hx-get="{{ url_for('get_snapshot_picker_step', step='commit').path }}"
hx-trigger="change"
hx-include="#snapshot-repository"
hx-target="#snapshot-commit-content"
hx-swap="innerHTML"
hx-indicator="#snapshot-commit-scope"
hx-sync="#snapshot-picker:replace">
<button type="button"><selectedcontent></selectedcontent></button>
<option value="">Choose a branch</option>
{% if step == "branch" %}
{% for value, label in options %}<option value="{{ value }}">{{ label }}</option>{% endfor %}
{% endif %}
</select>
<p class="picker-status"
role="status"
{% if step == "branch" and error %}data-state="error"{% endif %}>
{% if step == "branch" and repo %}
{{ message }}
{% if error %}
<button type="button"
class="btn btn-xs btn-secondary"
hx-get="{{ url_for('get_snapshot_picker_step', step='branch').path }}"
hx-include="#snapshot-repository"
hx-target="#snapshot-branch-content"
hx-swap="innerHTML"
hx-indicator="#snapshot-branch-scope"
hx-sync="#snapshot-picker:replace">Retry</button>
{% endif %}
{% else %}
Choose a repository first.
{% endif %}
</p>
</div>
</div>
<div id="snapshot-commit-scope" class="picker-load-scope">
<p class="picker-status picker-loading" role="status">Loading commits…</p>
<div id="snapshot-commit-content" class="picker-loaded">
{% block commit_step %}
<div class="picker-step">
<span class="picker-step-index" aria-hidden="true">3</span>
<div>
<label for="snapshot-commit" class="picker-step-label">Commit</label>
{% if step == "commit" and repo and ref %}
<form hx-get="{{ url_for('preview_snapshot').path }}"
hx-target="#snapshot-picker-body"
hx-swap="innerHTML"
hx-indicator="#snapshot-picker-scope"
hx-sync="#snapshot-picker:replace">
<input type="hidden" name="repo" value="{{ repo }}" />
<input type="hidden" name="ref" value="{{ ref }}" />
<select id="snapshot-commit"
class="picker-select"
name="commit"
required
{% if not options %}disabled{% endif %}>
<button type="button"><selectedcontent></selectedcontent></button>
<option value="">Choose a commit</option>
{% for value, label in options %}<option value="{{ value }}">{{ label }}</option>{% endfor %}
</select>
<p class="picker-status" role="status" {% if error %}data-state="error"{% endif %}>{{ message }}</p>
<div class="picker-actions">
<button type="button"
class="btn btn-sm btn-secondary"
commandfor="snapshot-picker"
command="close">Cancel</button>
<button type="submit"
class="btn btn-sm btn-primary"
{% if not options %}disabled{% endif %}>Select snapshot</button>
</div>
</form>
{% else %}
<select id="snapshot-commit" class="picker-select" disabled>
<button type="button"><selectedcontent></selectedcontent></button>
<option value="">Choose a commit</option>
</select>
<p class="picker-status" role="status">Choose a branch first.</p>
{% endif %}
</div>
</div>
{% endblock %}
</div>
</div>
{% endblock %}
</div>
</div>
{% endblock %}
<!-- djlint:on -->

View file

@ -0,0 +1,48 @@
{% if not confirmed %}
{% block selected_snapshot %}
<section id="selected-snapshot"
class="card overflow-hidden"
{% if confirmed %}hx-swap-oob="outerHTML"{% else %}hidden{% endif %}
aria-live="polite">
{% if confirmed %}
<div class="flex flex-wrap items-center justify-between gap-3 border-b border-border px-5 py-3">
<div class="flex flex-wrap items-center gap-2.5">
<span class="badge-success">Selected</span>
<span class="text-xs text-muted-foreground">Preview only — no share link has been created.</span>
</div>
<button type="button"
class="btn btn-xs btn-secondary"
hx-get="{{ url_for('preview_snapshot').path }}"
hx-target="#selected-snapshot"
hx-swap="outerHTML">Clear</button>
</div>
<dl class="snapshot-grid">
<div class="snapshot-cell">
<dt class="section-header-subtle">Repository</dt>
<dd class="snapshot-value">{{ repo }}</dd>
</div>
<div class="snapshot-cell">
<dt class="section-header-subtle">Branch</dt>
<dd class="snapshot-value">{{ ref }}</dd>
</div>
<div class="snapshot-cell">
<dt class="section-header-subtle">Commit</dt>
<dd class="snapshot-value">{{ commit[:12] }}</dd>
</div>
</dl>
{% endif %}
</section>
{% endblock %}
{% else %}
{% block preview_confirmation %}
<p role="status">Snapshot selected. No share link has been created.</p>
<div class="picker-actions">
<button type="button"
class="btn btn-sm btn-primary"
commandfor="snapshot-picker"
command="close"
autofocus>Done</button>
</div>
{{ self.selected_snapshot() }}
{% endblock %}
{% endif %}