myst/docs/plans/2026-09-04-public-link-inspection-implementation.md
2026-09-04 18:13:23 -04:00

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.