mirror of
https://github.com/ZTatman/myst.git
synced 2026-11-22 04:47:58 +00:00
3.8 KiB
3.8 KiB
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.forgejoclient 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/repositoriesbehind the current session dependency. - Return a normalized list of personally owned repositories.
- Add optional raw
inspection.forgejofields wheninspect=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
publicand 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
Grantrecord 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, andviewer_available: false. - Represent
token_hashas[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.mdbefore completing the PR.