tools-legacy/openspec/specs/fpagent-installer/spec.md

fpagent-installer Specification

Purpose

Lets a field laptop install the latest private fpagent release with a single public command, without ever handling the forge credential — the tools app proxies the private release and serves the installer.

Requirements

Requirement: Public installer endpoint

The app SHALL serve an installer script at /fpagent/install.sh that is reachable without authentication. When run, the script SHALL fetch the latest release metadata, choose a bundle for the host, verify the bundle's published sha256 checksum, extract it, and hand off to the extracted bundle's own installer. The script SHALL be served uncached.

Scenario: Installer is fetched anonymously

• WHEN a client requests /fpagent/install.sh without a session
• THEN the app returns the installer script and does not redirect to login

Scenario: Host-appropriate bundle is chosen

• WHEN the latest release offers both a bundle for the host's Ubuntu codename and a generic bundle
• THEN the installer uses the codename bundle

Scenario: Generic bundle is the fallback

• WHEN the latest release offers no bundle matching the host's Ubuntu codename
• THEN the installer uses the generic bundle

Scenario: Checksum is verified before extraction

• WHEN the installer downloads a bundle and its published checksum
• THEN it verifies the checksum before extracting and refuses to install when the checksum does not match

Scenario: Options are forwarded to the bundled installer

• WHEN the installer is invoked with options such as --enable-service or --check
• THEN it passes those options through to the extracted bundle's installer

Scenario: No compatible bundle

• WHEN the latest release contains no bundle for the host architecture
• THEN the installer exits with a failure message and installs nothing

Requirement: Release metadata endpoint

The app SHALL expose a same-origin endpoint that returns the latest release's tag and the names of its downloadable assets as same-origin URLs. The app SHALL authenticate to the private forge using the configured release key, SHALL omit asset names that are not valid asset names, and SHALL NOT reveal the release key or the forge host to clients.

Scenario: Latest release is returned

• WHEN a client requests the latest-release endpoint and the forge returns a release
• THEN the response carries the release tag and each asset's name and a same-origin URL under /fpagent/releases/download/

Scenario: Unsafe asset names are omitted

• WHEN the forge release lists an asset whose name is not a valid asset name
• THEN that asset does not appear in the response

Scenario: Release key is not exposed

• WHEN any client fetches the latest-release endpoint
• THEN the response body contains neither the release key nor the forge host

Scenario: Installer not configured

• WHEN the release key is not configured
• THEN the endpoint answers that the installer is not configured

Scenario: Forge unavailable

• WHEN the forge cannot be reached or returns an error for the latest release
• THEN the endpoint answers with a gateway error

Requirement: Release asset download proxy

The app SHALL stream a requested release asset to the client through a same-origin route, authenticating the upstream request with the release key so the client sends no credentials. It SHALL reject asset names that are not valid asset names and SHALL report a missing asset as not found.

Scenario: Asset is streamed without client credentials

• WHEN a client requests a release asset by tag and name without any credential
• THEN the app fetches it from the forge with the release key and streams its bytes to the client

Scenario: Invalid asset name is rejected

• WHEN a client requests an asset whose tag or name is not a valid asset name
• THEN the app rejects the request without contacting the forge

Scenario: Missing asset

• WHEN the forge reports the requested asset as not found
• THEN the app answers with not found

Scenario: Installer not configured

• WHEN the release key is not configured
• THEN the endpoint answers that the installer is not configured

Requirement: Installer credential stays server-side

The app SHALL read the private-forge release key from the GITEA_RELEASE_INSTALL_KEY environment variable. The key SHALL NOT appear in the installer script, in any release metadata response, or in any streamed asset.

Scenario: Served installer carries no credential

• WHEN a client fetches /fpagent/install.sh
• THEN the response contains no release key

Scenario: Credential supplied by the environment

• WHEN the release key is supplied in the environment
• THEN the installer and proxy endpoints use it without any change to the hardcoded configuration