docs: plan public link inspection API

This commit is contained in:
ZTatman 2026-09-04 18:13:23 -04:00
parent 53d95945d0
commit d14c29f94b
2 changed files with 296 additions and 0 deletions

View file

@ -0,0 +1,210 @@
# Public Link Inspection Design
## Goal
Build the first API-only slice of Firebreak's public share-link flow. The slice
must prove that Firebreak can authenticate a Forgejo user, identify repositories
that user personally owns, resolve a branch to an immutable commit, and persist a
public grant. It must expose the relevant JSON so the Forgejo payloads and the
created Firebreak record can be inspected before any code viewer is designed.
This PR does not implement a repository tree or file viewer.
## Scope
The PR includes:
- authenticated discovery of personally owned Forgejo repositories
- verification that the registered PAT belongs to the signed-in Forgejo identity
- server-side repository ownership verification
- branch-to-commit resolution
- public grant creation using an opaque share token
- raw Forgejo response inspection behind an explicit query parameter
- a normalized representation of eligible repositories and the created grant
- automated tests for the API, ownership boundary, token handling, and failures
The PR excludes:
- HTML, HTMX, or other link-creation UI
- repository tree or file rendering
- private links and email verification
- organization-owned repositories
- access logs and view counts
- grant revocation UI
- persistence of raw Forgejo responses
## Ownership Rule
Phase 1 supports personally owned repositories only.
Firebreak calls Forgejo's authenticated-user endpoint using the registered PAT
and compares that Forgejo user ID with the user's linked Forgejo OAuth identity.
The PAT is rejected if the IDs differ. For a selected repository, Firebreak then
requires the repository owner's Forgejo user ID to equal the authenticated PAT
user's ID. Pull, push, collaborator, administrator, or site-administrator access
does not satisfy this rule.
This check is performed server-side when the grant is created. A client-provided
owner name is never treated as proof of ownership.
## API
### Discover repositories
`GET /links/repositories?inspect=true`
The route requires an active Firebreak session and a registered Forgejo PAT. It
fetches the authenticated Forgejo user and that user's repositories, applies the
personal-ownership rule, and returns:
```json
{
"repositories": [
{
"owner": "zach",
"name": "example",
"full_name": "zach/example",
"default_branch": "main",
"private": true
}
],
"inspection": {
"forgejo": {
"authenticated_user": {},
"repositories": []
}
}
}
```
`repositories` is the normalized Firebreak contract. `inspection` is included
only when `inspect=true` and contains the unmodified JSON bodies received from
Forgejo after response parsing. Firebreak does not persist the inspection data.
### Create a public grant
`POST /links/?inspect=true`
Request:
```json
{
"repo_owner": "zach",
"repo_name": "example",
"branch": "main",
"expires_at": "2026-09-11T12:00:00Z",
"link_type": "public"
}
```
The route accepts public grants only. `expires_at` must be timezone-aware and in
the future. Firebreak fetches the authenticated Forgejo user, repository, and
branch; verifies identity and ownership; resolves the branch to its commit SHA;
and creates the grant in one database transaction.
Successful response: HTTP 201.
```json
{
"created_grant": {
"id": "2d792f51-10a7-46cf-9b88-7a0c9f6ea769",
"repo_owner": "zach",
"repo_name": "example",
"commit_sha": "abc123",
"grant_type": "public",
"created_at": "2026-09-04T12:00:00Z",
"expires_at": "2026-09-11T12:00:00Z",
"revoked_at": null,
"recipient_email": null,
"token_hash": "[redacted]"
},
"share_url": "https://share.example.com/s/opaque-token",
"viewer_available": false,
"inspection": {
"request": {
"repo_owner": "zach",
"repo_name": "example",
"branch": "main",
"expires_at": "2026-09-11T12:00:00Z"
},
"forgejo": {
"authenticated_user": {},
"repository": {},
"branch": {}
},
"ownership": {
"allowed": true,
"reason": "repository owner matches authenticated Forgejo user"
}
}
}
```
`created_grant` mirrors the persisted database record except that the token hash
is always represented as `[redacted]`. The usable share URL is returned once.
Its viewer endpoint is intentionally unavailable in this PR, which is made
explicit by `viewer_available: false`.
## Token Handling
Firebreak generates a cryptographically random URL-safe token. The raw token is
used only to construct the one-time response URL. Firebreak stores a SHA-256 hash
in `Grant.token_hash`; it never stores the raw token.
Inspection responses never contain PATs, OAuth credentials, encryption keys,
authorization headers, or the stored token hash. Raw Forgejo JSON bodies are
returned only to the authenticated Firebreak user that requested inspection.
## Components
- A thin Forgejo service owns HTTP mechanics, URL construction, response parsing,
and typed upstream failures.
- A token helper pairs PAT decryption with the current application cipher.
- The links router owns request validation, session enforcement, ownership
decisions, grant construction, and response serialization.
- Pydantic response models separate the stable Firebreak contract from optional
inspection payloads.
- The existing `Grant` model remains the persisted source of truth. Raw Forgejo
responses and branch names are not stored.
## Error Handling
- `401` when there is no active Firebreak session
- `409` when the signed-in user has not registered a PAT
- `403` when the PAT identity differs from the OAuth identity or the repository
is not personally owned by that identity
- `404` when Forgejo cannot find the selected repository or branch
- `422` for unsupported link types, invalid names, naive timestamps, or an
expiration that is not in the future
- `502` when Forgejo is unreachable, returns an unexpected response, or rejects
an otherwise valid upstream request
- `500` for a failed database transaction, after rollback and without exposing
database details
Failures identify the stage (`identity`, `repositories`, `repository`, `branch`,
or `grant`) without exposing credentials. An inspection response may include only
the safe upstream JSON successfully received before the failure.
## Testing
Tests use mocked Forgejo HTTP responses and a test database/session dependency.
They cover:
- repository discovery returns raw and normalized JSON
- inspection data is absent unless requested
- the PAT user ID must match the linked OAuth identity ID
- collaborators and other non-owner users are rejected
- a personally owned repository is accepted
- a branch is pinned to the exact Forgejo commit SHA
- only a token hash is persisted
- the raw token appears only in the one-time share URL
- past or timezone-naive expirations are rejected
- Forgejo transport, authentication, not-found, and malformed-payload failures
- database failure rolls back without returning a created grant
## Follow-up Boundary
The next PR can use the persisted grant and returned share token to implement
viewer-side lookup and expiration/revocation enforcement. Tree shape and file
payload decisions will be based on observed Forgejo JSON from this inspection
slice rather than assumptions made in advance.

View file

@ -0,0 +1,86 @@
# Public Link Inspection Implementation Plan
## Objective
Implement and verify the approved API-only public-link inspection slice without
adding a code viewer or link-creation UI.
## 1. Establish the test harness
- Add the minimum Python test dependencies needed for FastAPI route and async
service tests.
- Add fixtures for an authenticated Firebreak session, linked Forgejo identity,
registered encrypted PAT, application settings, and database session.
- Provide mocked Forgejo HTTP responses without contacting a live service.
- Confirm the empty baseline test suite, Ruff, and mypy run locally.
## 2. Centralize Forgejo API access
- Add a thin `app.services.forgejo` client for authenticated GET requests.
- Preserve parsed upstream JSON so the router can return inspection data.
- Define typed failures that retain safe status and stage information.
- Test URL construction, authentication headers, non-2xx responses, malformed
JSON, and transport errors.
## 3. Add application-aware PAT access
- Add one helper that decrypts the signed-in user's PAT through the configured
Fernet cipher.
- Convert missing PAT and decryption failures into explicit route-level errors.
- Ensure no exception or response contains the raw PAT.
## 4. Implement identity and ownership checks
- Fetch the PAT-authenticated Forgejo user.
- Load the signed-in user's Forgejo linked identity and compare immutable Forgejo
user IDs.
- Fetch repository metadata and require its owner ID to match that user ID.
- Reject collaborators, administrators, organization repositories, and PAT/OAuth
identity mismatches.
- Add focused tests for every allow and deny case.
## 5. Implement repository discovery JSON
- Add `GET /links/repositories` behind the current session dependency.
- Return a normalized list of personally owned repositories.
- Add optional raw `inspection.forgejo` fields when `inspect=true`.
- Verify the inspection envelope is omitted by default and contains no secrets.
## 6. Implement public grant creation
- Replace the 501 handler with an authenticated HTTP 201 route.
- Restrict the accepted link type to `public` and require a future,
timezone-aware expiration.
- Fetch and verify repository metadata, then fetch the requested branch.
- Extract the immutable commit SHA from the branch response.
- Generate a URL-safe token, hash it with SHA-256, and create the existing
`Grant` record in a single transaction.
- Refresh the created row so server-generated ID and timestamps are returned.
- Build the future share URL from the configured Firebreak public base URL.
## 7. Serialize created and inspection data
- Return a stable `created_grant`, `share_url`, and `viewer_available: false`.
- Represent `token_hash` as `[redacted]`; never serialize the stored hash.
- When `inspect=true`, include the request, raw Forgejo user/repository/branch
responses, and the ownership decision.
- Add response-model tests that fail if credentials or hashes appear.
## 8. Complete error and transaction coverage
- Map missing session, missing PAT, identity mismatch, ownership denial,
repository/branch not found, upstream failures, invalid expiration, and
database failure to the approved status codes.
- Roll back failed writes and confirm no grant remains after an error.
- Keep messages actionable while avoiding upstream credentials and database
details.
## 9. Validate and document the observed payloads
- Run the complete Python test suite, Ruff, mypy, and template checks affected by
the change.
- Exercise the routes against the configured development Forgejo instance when
available and capture representative redacted JSON in the PR description.
- Update the Phase 1 progress list only for behavior proven by the final tests.
- Record any newly discovered repository-specific obstacle in `agents.md` before
completing the PR.