Files
noahandClaude Opus 5.5 b26f389460 Report relay: files the app's bug reports as Gitea issues
tools/report-relay is a dependency-free Python service. It takes the
JSON the app's Bug report button sends, validates it (type, text,
context and log sizes), scrubs the log a second time, rate-limits (5
per client IP and 60 in all per hour, 4 in flight), neutralises
@mentions, and files one issue in blueflare/alkane-toolkit with the
labels bug/ui/feature and from-app. It stores nothing and logs one
line per report without its text.

It runs on the Gitea host behind the shared nginx at
https://gitea.bluefla.re/alkane-report/ as the scoped alkane-reporter
bot (team alkane-reporters: issues write, code read, alkane-toolkit
only). See tools/report-relay/README.md. Its tests run in verify's
unit-test step.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BdKQBRg6YCM1XXQCTnD5GF
2026-11-04 11:04:15 -06:00

2.8 KiB

Report relay

Files the app's bug reports and feature requests as issues in blueflare/alkane-toolkit. The app's Bug report button posts the report here; the relay holds the only token, so the public app download carries no secret.

app --HTTPS--> gitea.bluefla.re/alkane-report/ (nginx) --> relay --> Gitea API

What it does

  • POST /v1/report takes the JSON the app sends (kind, text, version and OS context, optional log) and answers 201 {"number", "url"} or an error {"error": "..."} the app shows as is. GET /healthz answers 200.
  • Checks: type is bug, ui or feature; text 1 to 8,000 characters; each context value at most 120 printable characters; log at most 16 KiB; body at most 64 KiB (nginx enforces the same).
  • Rate limits, in memory: 5 reports per client IP per hour and 60 in all. Over the limit: 429 with Retry-After. At most 4 reports in flight. The client IP is X-Real-IP from nginx. Office LAN clients reach nginx through the router's hairpin NAT, so they share one IP and one limit.
  • Scrubs the log a second time (the app scrubs first): password, token, secret and similar values, Authorization/Cookie values, URL passwords and PEM private keys become [redacted].
  • @name in a report cannot notify anyone (a zero-width space follows @).
  • The issue title is the text's first line (up to 100 characters). The body has the type, a context table, the text, and the log in a collapsed block. Labels: the type (bug, ui, feature) and from-app.
  • Nothing is stored. Each report leaves one log line: the client IP and the outcome (filed #N, refused <status>, rate limited, tracker error), never the report's text.

Gitea account

Issues are filed as alkane-reporter, a local non-admin user with a random password that is never used. Its only access is the org team alkane-reporters (units repo.code: read, repo.issues: write) on alkane-toolkit. Its token alkane-toolkit-bug-reports has the scopes write:issue and read:repository. This mirrors FLARE's flare-reporter.

Deployment

On the Gitea host, recorded in the flare-deployment repository (runbooks/alkane-report-relay.md):

# in /opt/flare/deploy/alkane-report-relay, holding relay.py, Dockerfile, compose.yml
PROXY_NETWORK=flare_default docker compose -p alkane-report-relay up -d --build

The token file is secrets/gitea_token next to the compose file (directory 0700, never committed). nginx routes location /alkane-report/ in the gitea.bluefla.re server block to alkane-report-relay:8080.

Tests

python3 tools/report-relay/test_relay.py

They run the real HTTP handler against a fake Gitea: filing, scrubbing, mention handling, validation, size and rate limits, and tracker errors. CI runs them in the verify workflow's unit tests.