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

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.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.