infra/license-bot/README.md

# license-bot

Adds the AGPL-3.0 license header to files a pull request **adds** without one,
in a separate, revertable commit on the pull request head, comments on the pull
request, and posts the `license-bot / addlicense` commit status that branch
protection requires before merging. Works for same-repository pull requests
**and** for fork pull requests.

Version v0.0.1 takes no arguments and has one trigger: **Gitea webhooks**.

## Why a service instead of a Gitea Actions workflow

- Gitea evaluates a pull request's workflows **from the head branch**, so a
  contributor (or a fork) can edit, delete or fake the job — including reporting
  a green status. A workflow therefore cannot be an enforcement boundary.
- Actions runs triggered by fork pull requests get no repository secrets and a
  read-only token, so a workflow can never hold the credentials needed to push a
  commit back to a contributor's fork.
- **Nothing permissive lives in Actions.** The bot-account token exists only in
  this service's environment on the Gitea host. An in-repo PR workflow can read
  every repo and org Actions secret (measured: the value left the host over HTTP
  while the log showed `***`), so the fewer credentials reachable from CI, the
  smaller the blast radius.
- The merge gate is the **commit status**, not a workflow run: a required
  branch-protection check that was never posted blocks the merge (`405`), while
  a required *scoped workflow* that never ran does not (`200`, measured on
  1.27.2).

## How it works

1. On startup it reconciles once: every open pull request of every allowlisted
   repository whose head does not already carry a successful
   `license-bot / addlicense` status is checked. The status is the durable record
   of what the bot has already resolved, so the scan is self-healing without a
   cursor.
2. While running it receives Gitea `pull_request` webhooks (HMAC-SHA256
   verified against `WEBHOOK_SECRET`, duplicate delivery ids ignored) and
   processes `opened`, `synchronize`, `reopened` and `ready_for_review`.
3. It re-reads the pull request from the API (the payload is only a hint) and
   lists the files the pull request **changed** that still exist at the head:
   `added`, `modified`, `renamed` and `copied` are all in scope, so an existing
   unlicensed file gets its header the first time any pull request touches it.
   Removals are skipped (there is no content left to license), and a
   deletion-only pull request is reported `success` ("no changed files need a
   license header") with no comment and no commit. Otherwise it posts `pending`
   for those files and logs what it is about to check.
4. It clones the head branch (in-repo or fork), runs `google/addlicense`
   v1.2.0 with the repository's own `.license-header.tpl` and `.licenseignore`
   over exactly those files. Because the scope includes modified files, a
   `.licenseignore` that is missing an entry makes the bot rewrite a file the
   contributor only touched — keep vendored and generated paths listed there.
5. If a header was added: it creates **its own commit on top of the pull request
   head** — never an amend, never a force-push. The contributor's commit keeps
   its sha, message and author; the bot is the committer of the extra commit,
   whose body says it can be reverted or dropped freely.
6. It pushes with a plain fast-forward `git push`. If the branch moved meanwhile
   the push is rejected; the bot drops its local work, re-reads the tip,
   re-applies the headers and retries (up to 5 attempts, then the next event
   retries). It never rewrites somebody else's history.
7. It replaces its comment — the previous one is deleted and a fresh one posted,
   never edited in place, so the message always sits at the bottom of the
   timeline next to the latest status — and resolves the status: `success` when
   the head carries the headers, `failure` when the contributor has to add them
   by hand (maintainer edits disabled), `error` if the bot itself failed. A
   pass that finds nothing left to fix deletes a stale problem comment so a
   resolved failure never sits next to a green status. A crash leaves the status
   `pending`, which keeps the gate closed until the startup reconcile resolves it.

Loop safety: the bot's own commit produces one more `synchronize` event; that
run finds nothing to fix and reports success. Processed `(repo, PR, sha)`
triples are cached in memory and already-green heads are skipped.

## Failure semantics

Webhooks are the only trigger, so **a check that did not run means the service
was down**, not that some other component failed. The consequences are bounded
by design:

- If the service is down when a pull request opens, no status is posted; the
  gate (if enabled) refuses to merge — nothing unlicensed slips through.
- When the service starts, the reconciliation pass processes every open pull
  request that is not green, including ones left `pending` by a crash.
- A failed *check* (push refused, API error) resolves the status to `failure`
  or `error` and comments, so a parked pull request is visible rather than
  silently green.

## Configuration

All configuration is environment driven — the image contains no secrets and the
process takes no arguments.

| Variable | Default | Meaning |
| --- | --- | --- |
| `GITEA_URL` | dev-VM fallback, required by the compose | Target instance base URL. On an instance whose Gitea runs on the same Docker daemon use the network alias (e.g. `http://gitea:3000`) so the bot needs no egress and no published port. |
| `GITEA_PUBLIC_URL` | `GITEA_URL` | URL used for the links in the bot's comments. Set it when `GITEA_URL` is the internal Docker alias, otherwise a reader's browser cannot resolve `http://gitea:3000`. |
| `GITEA_TOKEN` | — (required) | Bot-account token with write access to the target repositories. Needs `write:repository` (clone/push/commit status) plus `read:issue` + `write:issue` (read the files list, post/update the comment) — a repository-only token authenticates but cannot comment. |
| `WEBHOOK_SECRET` | — (required) | HMAC-SHA256 secret of the org webhook. Every delivery is rejected unless `X-Gitea-Signature` matches. |
| `REPOS` | the five Dcntrlized repos | Comma-separated `owner/name` allowlist. Nothing outside it is ever touched. |
| `STATUS_CONTEXT` | `license-bot / addlicense` | Commit-status context; must equal the branch-protection string byte for byte. |
| `LISTEN` | `:8080` | Webhook and health listen address. |
| `DRY_RUN` | `false` | Inspect and report but never commit or push. |
| `BOT_NAME` / `BOT_EMAIL` | `Dcntrlized Auto CopyLeft Bot` / `[email protected]` | Committer identity of the bot's commit. |
| `HOLDER` | `Dcntrlized` | `addlicense -c` value. |
| `ADDLICENSE_BIN` | `addlicense` | `addlicense` executable. |
| `WORK_ROOT` | `$TMPDIR` | Where per-pull-request worktrees are created. |
| `LOG_LEVEL` | `info` | `debug`, `info`, `warn` or `error`. |

Copy `.env.example` and fill in `GITEA_TOKEN` and `WEBHOOK_SECRET`. Never commit
that file.

Routes: `POST /hook` (webhook, `POST /webhook` is accepted as an alias) and
`GET /healthz` (container healthcheck).

## Deploying to an instance

Three values plus one command:

```sh
cp .env.example .env
# GITEA_URL      = the instance (network alias when Gitea shares the daemon)
# GITEA_TOKEN    = a DEDICATED BOT ACCOUNT token, never an admin token
# WEBHOOK_SECRET = openssl rand -hex 32
# NETWORK_NAME   = the network the Gitea container already runs on
./deploy.sh
```

`deploy.sh` creates the network if missing, builds and starts the container,
waits for the healthcheck, verifies the token against `GET /api/v1/user` and
verifies that `http://license-bot:8080/hook` resolves **from Gitea's own
network** — the exact URL the webhook has to reach. It then prints the two
instance-side steps with ready-to-paste commands:

0. **Let Gitea reach the service (prerequisite).** With its default
   `security.ALLOWED_HOST_LIST`, Gitea refuses to deliver a webhook to an
   internal Docker alias: the delivery is recorded as failed with
   `webhook can only call allowed HTTP servers … deny 'license-bot(<ip>)'` even
   though the URL is perfectly reachable from inside the container. Add
   `[security]` → `ALLOWED_HOST_LIST = license-bot` to Gitea's `app.ini` (or
   list the private subnet) and restart Gitea. This is a Gitea-side allowlist,
   not a networking problem — check it first if deliveries never arrive.
1. **The webhook (required).** An **organization** webhook to
   `http://license-bot:8080/hook`, content type JSON, secret = `WEBHOOK_SECRET`,
   events = `pull_request`. Without it nothing is ever checked.
2. **The gate.** Branch protection on each default branch requiring the exact
   context `license-bot / addlicense`, plus at least one approval so the author
   cannot self-merge. Verify afterwards that the context string matches exactly:
   a mismatch silently never blocks anything.

A safe first run is `DRY_RUN=true docker compose up -d --force-recreate`: the
bot comments and posts statuses but never commits.

There is no Actions runner dependency anywhere in this path: the bot only needs
to be reachable from Gitea and to reach Gitea.

## Security notes

- The token is only ever read from the environment. It is never logged: URLs
  embedded in git errors are redacted before they reach a log line or a PR
  comment.
- Webhook deliveries are rejected unless the HMAC-SHA256 signature matches, and
  duplicate delivery ids are ignored.
- Only repositories in `REPOS` are processed.
- The bot never rewrites history: it adds a commit and uses a plain
  fast-forward push, so a push that lost a race against a new contributor commit
  is rejected. The bot then discards its local commit, re-reads the branch,
  re-runs the check on the new tip and pushes again, repeating until it succeeds
  or finds nothing left to change (bounded at 5 attempts, after which the next
  event retries). Nothing is ever overwritten.
- If the contributor disabled maintainer edits on the pull request, the push is
  refused by the server; the bot then comments that the header must be added by
  hand and reports a failing status. It never bypasses that.

### Threat model (measured on Gitea 1.27.2)

The full per-test methodology and raw observations are in
[`SECURITY.md`](SECURITY.md). Summary:

- **Merge gate.** Branch-protection checks are enforced on the merge API: a
  normal writer's merge is refused `405 Not all required status checks
  successful` when the required context is **absent**, still `405` when it is
  `pending`, and allowed (`200`) on `success`. A fork PR run cannot post any
  status (`403 user should have a permission to write to a repo`). Requiring the
  exact context `license-bot / addlicense` is therefore a fail-closed gate: if
  the bot is down and never posts, nothing merges.
- A repository **writer** can forge any context (`201`); write access is the
  trust boundary, as it is for any other repository change.
- **Do not use required scoped workflows as the gate on 1.27.2.** With a scoped
  workflow marked required and failing, a writer's `POST /pulls/{n}/merge`
  returned `200` — the requirement is UI-only.
- **Log masking is not protection.** An in-repo PR workflow exfiltrated a repo
  secret and an org secret over HTTP (`201`) although the log showed `***`. The
  only real question is reachability plus egress — which is why the bot's token
  stays on the host.
- **RESOLVED — job-container host read (T2.3).** The dev runner used to expose
  `/var/run/docker.sock` to job containers. It now pins
  `container.docker_host: "-"`, `privileged: false`, `valid_volumes: []` and an
  `--internal` job network; a real job measured `SOCKET_ABSENT`, no internet,
  the host IP unreachable and `gitea:3000` reachable. Configs + deploy script:
  `infra/gitea-runner/`.
- **STILL OPEN: the org `TOKEN` Actions secret.** It is the site-admin token
  (`sha256` matched, T2.4). The bot no longer has anything to do with it, so it
  can be deleted as soon as `release.yaml` gets its own least-privilege
  `write:package` token, and the bot account's own token should be rotated onto
  a dedicated non-admin account scoped to the five repositories.