From d14c29f94b85b3a6b5cb2aee1425d874d89c5da5 Mon Sep 17 00:00:00 2001 From: ZTatman Date: Fri, 4 Sep 2026 18:13:23 -0400 Subject: [PATCH] docs: plan public link inspection API --- ...026-09-04-public-link-inspection-design.md | 210 ++++++++++++++++++ ...4-public-link-inspection-implementation.md | 86 +++++++ 2 files changed, 296 insertions(+) create mode 100644 docs/plans/2026-09-04-public-link-inspection-design.md create mode 100644 docs/plans/2026-09-04-public-link-inspection-implementation.md diff --git a/docs/plans/2026-09-04-public-link-inspection-design.md b/docs/plans/2026-09-04-public-link-inspection-design.md new file mode 100644 index 0000000..50b3783 --- /dev/null +++ b/docs/plans/2026-09-04-public-link-inspection-design.md @@ -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. diff --git a/docs/plans/2026-09-04-public-link-inspection-implementation.md b/docs/plans/2026-09-04-public-link-inspection-implementation.md new file mode 100644 index 0000000..24f95b7 --- /dev/null +++ b/docs/plans/2026-09-04-public-link-inspection-implementation.md @@ -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.