4.8 KiB
Inspect repository and grant JSON
Firebreak exposes repository discovery and public grant creation as authenticated
JSON endpoints. Sign in through Forgejo, then register a PAT from the same account
with read:user and read:repository scopes in Settings.
The owner check compares Forgejo IDs. Collaborator access, administrator access, and organization ownership do not qualify. All requests require your active Firebreak session; inspection data is never exposed through the share URL.
See what Forgejo returns
While signed in, open /links/repositories?inspect=true on your Firebreak host in
the browser. The response includes:
repositories: personally owned repositories normalized for Firebreakinspection.forgejo.authenticated_user: the PAT-authenticated Forgejo userinspection.forgejo.repositories: the upstream repository JSON for this page, including accessible repositories excluded by the personal-owner filterpage,limit, andnext_page: pagination; request the next page when present
For example, /links/repositories?inspect=true&page=2&limit=30 inspects page 2.
Pagination follows the upstream page boundaries, so a page can contain no eligible
repositories while still having a next_page. Omit inspect=true to receive only
the normalized results and pagination.
The inspection payload keeps upstream fields and structure, with credential
fields, credential-bearing URLs, and echoed PAT values redacted. It is returned
only for this request and is not saved in the database. Responses use
Cache-Control: no-store.
Create and inspect a grant
Open /docs on the same Firebreak host after signing in. Expand POST /links/,
click Try it out, set inspect to true, and supply this body with your own
repository and a future expiration:
{
"repo_owner": "zach",
"repo_name": "example",
"branch": "main",
"expires_at": "2099-01-01T12:00:00Z",
"link_type": "public"
}
The same-origin request uses your existing browser session. You do not need to copy a session cookie or paste your PAT into the request. This operation creates a real grant each time it succeeds; there is no preview/dry-run mode.
The JSON request must use Content-Type: application/json. The timestamp must
include a timezone, and the branch must exist. Branch names such as
feature/example are supported. Private links and recipient-email fields are
rejected in this slice.
The HTTP 201 response separates:
created_grant: the saved Firebreak record, including its database-generated ID and timestamps;token_hashis always[redacted]share_url: a freshly generated bearer link, returned once; the database contains only the SHA-256 hash of its tokenviewer_available:false, because/s/{token}is not implemented yetinspection: the validated request, upstream user/repository/branch JSON, and the successful ownership decision
The commit SHA comes from Forgejo's branch.commit.id and stays pinned even when
the branch moves. Grant creation records expiration, but viewer-side expiration
and revocation enforcement will arrive with the viewer. Treat the one-time share
URL as a secret and keep it out of logs or screenshots you publish.
See example responses. These examples
use mocked Forgejo data and a real test database; they are not a capture from
your Forgejo account. IDs/times are illustrative and the one-time share token
has been replaced with [returned-once].
Failures
| Status | Meaning |
|---|---|
| 401 | Missing, expired, or revoked Firebreak session |
| 403 | PAT account mismatch, or repository not personally owned |
| 404 | Forgejo repository or branch not found |
| 409 | No registered PAT |
| 415 | Request did not use application/json |
| 422 | Invalid names, expiration, pagination, or unsupported request fields |
| 502 | Forgejo rejected the PAT, was unreachable, or returned invalid data |
| 503 | Setup, public URL, Forgejo transport, or PAT decryption needs attention |
| 500 | Grant could not be saved; transaction rolled back |
Upstream and grant failures include a detail.stage and an actionable message.
Failures do not echo raw upstream error bodies, request values, database details,
or partial inspection payloads.
Run the tests
From the repository root:
uv --directory web run pytest -q
uv --directory web run mypy app
Tests default to an isolated in-memory SQLite database with a mocked Forgejo
transport. For PostgreSQL, set FIREBREAK_TEST_DATABASE_URL to a disposable local
test database using the postgresql+asyncpg:// scheme. Each test creates and drops
its own randomly named schema; the account must have schema-creation privileges.
Tests never use DATABASE_URL or contact the configured Forgejo instance.
Upstream reference: Forgejo API usage
and the instance's /swagger.v1.json schema.