mirror of
https://github.com/ZTatman/myst.git
synced 2026-11-21 04:17:59 +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