mirror of
https://github.com/ZTatman/myst.git
synced 2026-11-22 12:57:58 +00:00
docs: plan public link inspection API
This commit is contained in:
parent
53d95945d0
commit
d14c29f94b
2 changed files with 296 additions and 0 deletions
210
docs/plans/2026-09-04-public-link-inspection-design.md
Normal file
210
docs/plans/2026-09-04-public-link-inspection-design.md
Normal 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.
|
||||||
|
|
@ -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.
|
||||||
Loading…
Add table
Reference in a new issue