mirror of
https://github.com/ZTatman/myst.git
synced 2026-11-22 12:57:58 +00:00
86 lines
3.8 KiB
Markdown
86 lines
3.8 KiB
Markdown
# 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.
|