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

7.1 KiB

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:

{
  "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:

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

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