Support public BRIGX sessions from GitLab, GitHub Gists, and Zenodo

[happykhan]

Summary

Extend BRIGX's existing public GitHub session loading so exported .brigx-session.json results can also be opened from:

1. public GitLab repositories;
2. public GitHub Gists; and
3. Zenodo records or files.

This is a planned enhancement only. Keep the existing provider-neutral routes:

/preview?url=<public-session-url>  # read-only
/app?url=<public-session-url>      # editable

Why

These providers cover source-controlled sessions, lightweight one-file sharing, and stable citable research deposits. Support must remain an explicit allowlist of known public-data providers, not a generic URL fetcher.

Proposed architecture

Refactor lib/remoteJson.ts from GitHub-specific functions into a remote-session provider adapter registry. Each adapter should:

• recognise supported URL shapes;
• validate HTTPS and the exact hostname;
• resolve a human-facing page URL to an approved downloadable/API URL;
• never forward cookies, credentials, or tokens;
• provide provider-neutral result/error handling.

Rename normalizeGitHubJsonUrl and fetchGitHubJson to provider-neutral equivalents while preserving existing GitHub behaviour.

Delivery plan

Phase 1: foundation and GitLab

Support public GitLab.com URLs:

• https://gitlab.com/<namespace>/<repo>/-/blob/<ref>/<path>
• https://gitlab.com/<namespace>/<repo>/-/raw/<ref>/<path>

Convert /-/blob/ to /-/raw/ without trying to split branch names from file paths. Do not allow arbitrary self-hosted GitLab domains initially.

Phase 2: GitHub Gists

Support public Gist page URLs and direct public Gist raw URLs.

For a Gist page:

• query the public Gist metadata API;
• automatically select a file only when there is exactly one recognised BRIGX session JSON;
• when multiple candidates exist, return a clear error requesting a direct raw-file URL;
• reject truncated or unavailable content unless it can be fetched through an approved returned raw URL.

Phase 3: Zenodo

Support direct public Zenodo file URLs and record URLs such as https://zenodo.org/records/<record-id>.

For a record:

• resolve metadata through Zenodo's public API;
• automatically select a file only when exactly one recognised BRIGX session JSON exists;
• return a clear ambiguity/no-session error otherwise;
• use the API-provided file link;
• load the exact requested record version rather than silently moving to the newest version.

Recognised content

Initially recognise:

• *.brigx-session.json
• any other currently documented BRIGX result/session suffix

Downloaded content must still pass the existing import/schema validation. Filename matching is not sufficient validation.

User interface

• Rename GitHub-specific labels/help text to “Public BRIGX session URL”.
• List supported providers near the input.
• Show resolution failures in plain language.
• Preserve the original source URL in the address bar.
• Preserve the existing preview/edit distinction.
• Do not imply BLAST can be rerun until source FASTA files are re-added.

Security requirements

Preserve the current safeguards:

• HTTPS only and exact-hostname allowlisting;
• public resources only;
• credentials: 'omit';
• no authentication tokens in URLs or browser storage;
• 20-second timeout;
• 25 MB response limit checked from both Content-Length and actual bytes;
• existing session/schema validation;
• no redirects to unapproved origins.

Update public/_headers CSP only with the minimum exact API/raw origins required. Verify the final fetch hostname against the allowlist.

Tests

Unit

• URL recognition/conversion for every supported shape.
• Reject HTTP, lookalike hosts, embedded credentials, unsupported paths, and arbitrary domains.
• Existing GitHub blob/raw compatibility.
• Gist and Zenodo zero/one/multiple-candidate handling.
• Oversized response, timeout, non-JSON, HTTP error, and unsafe redirect handling.
• Schema/import failure after successful download.

End-to-end

For both /preview?url= and /app?url=:

• load a stable public fixture for every provider;
• verify the circular result renders;
• verify preview is read-only and app mode exposes editing controls;
• verify source FASTA messaging;
• verify invalid/unavailable URLs have a usable error and recovery path.

Use small project-controlled fixtures wherever practical.

Acceptance criteria

• Existing GitHub blob/raw URLs work unchanged.
• Public GitLab.com blob/raw URLs load in preview and edit modes.
• Public GitHub Gists resolve deterministically and load in both modes.
• Public Zenodo record/direct-file URLs resolve deterministically and load in both modes.
• Multi-file Gists and Zenodo records never choose ambiguously.
• Unsupported or unsafe URLs are rejected before fetching.
• CSP permits only the exact new origins required.
• The size limit, timeout, credential omission, and schema validation remain enforced.
• UI copy and documentation explain supported providers and routes.
• Unit, end-to-end, architecture, security, and production build checks pass.

Out of scope

• arbitrary HTTPS URLs;
• private/authenticated repositories, OAuth, or URL tokens;
• self-hosted GitLab;
• Google Drive or Dropbox;
• Bitbucket, OSF, and Figshare;
• provider-specific routes or changing the url parameter;
• increasing the 25 MB limit.

Bitbucket can be assessed in a separate follow-up after usage of these providers is understood.