# Workflow

One issue per unit of work, one branch and one PR per issue:

* ensure a tracked issue exists with a definition of done
* branch from `next` (never from `main`)
* do the work; open a PR based on `next` (never on `main`)
* pass an independent review, then the manager squash-merges into `next`
* push; nothing stays local-only

`next` is the branch for the next milestone and must stay green and
mergeable to `main` without notice. One `next` -> `main` PR accumulates
the milestone; releases are cut from `main` separately.

Issue branches do NOT touch this file — the manager maintains it on
`next`. Every branch editing `TODO.md` conflicts with every other
(#112).

# Status

pre-1.0. No git tags exist. `main` (4f5ecb1) is a working webhook proxy
with auth, CSRF/SSRF protections, login rate limiting, Slack target,
event retention (#63), the database archiving target (#43), the admin
password change flow (#65), policy compliance (#6), pinned lint tooling
(#55), and fail-loud configuration parsing (#80).

`next` (9bfd033) holds the completed 1.0.0 milestone: every issue in it
is closed, and it is verified green by cache-defeated container runs
rather than by the CI badge, which can pass without executing anything
(#119). Note: TODO.md was deliberately deleted from this repo in f9a9569
(2026-03-01, #6); its content was folded into the README TODO section,
which this draft reconstructs as of 2026-07-06.

# Next Step

Tag 1.0.0 from `main` once the milestone PR merges, then repair the CI
gate (#119) before the next cycle's work lands — a gate that can report
success without running is the one thing every other guarantee here
rests on.

# Completed Steps

- 2026-08-12 Bound the `X-Forwarded-For` scan's allocation to the hop
  cap: the reverse walk cuts entries with `strings.LastIndexByte`
  instead of joining and splitting, so a 1 MB header allocates 16 bytes
  rather than 1.6 MB per request on the unauthenticated receiver.
  Semantics proven unchanged by differential testing against the
  previous implementation (#133)
- 2026-08-12 Cap the `X-Forwarded-For` hop walk at 64 entries, so an
  attacker-supplied chain cannot burn unbounded CPU in the rate-limit
  key function; running off the end falls back to the peer address
  (#124)
- 2026-08-12 Gate forwarded-header trust behind a `TRUSTED_PROXIES` CIDR
  list: all three rate limiters key on the connection's own address
  unless the direct peer is a configured proxy, in which case
  `X-Forwarded-For` is walked right to left for the first non-proxy hop.
  Default trusts nothing, and a set-but-unparseable value aborts
  startup. Before this, any client could mint a fresh bucket or drain
  another's by rotating a spoofed header (#88)
- 2026-08-11 Web UI cleanup: nav terminology unified on Webhooks, the
  Profile settings placeholder removed, a progressive-enhancement copy
  button for the entrypoint URL, and retention form copy that states the
  actual policy (deletion by the reaper, 0 retains forever) (#57)
- 2026-08-09 Inactivity-based session timeout: sliding idle expiry
  (`SESSION_IDLE_TIMEOUT`, default `24h`) refreshed on authenticated
  requests, with the 7-day absolute cap kept as an independent
  backstop that activity never extends (#66)
- 2026-08-09 Restart recovery and the 60s retry sweep terminally fail an
  orphaned `retrying` delivery whose target type no longer supports
  retries, recording a `DeliveryResult` with the reason instead of
  leaving the delivery stuck forever (#82)
- 2026-08-09 Root the delivery engine's worker pool and the retention
  reaper's sweep loop at `context.Background()` rather than the fx
  `OnStart` hook context (#97), which carries fx's 15s start timeout and
  killed both roughly fifteen seconds after boot: the proxy silently
  stopped delivering webhooks entirely, and the reaper never ran a
  single sweep under its default one-hour interval
- 2026-08-09 Archive writer lifecycle (#89): deleting a webhook (or its
  last `database` target) evicts the cached archive writer and closes
  its handle while deliberately leaving `archive-{webhookID}.db` on
  disk, and a new `ArchiveSweeper` prunes idle archives on the existing
  `RETENTION_SWEEP_INTERVAL` without ever creating an archive file
- 2026-08-09 Configuration parsing fails loudly on set-but-unparseable
  environment values: `envInt` removed in favour of `envPositiveInt`
  plus a `PORT` range check, `envBool` now parses with
  `strconv.ParseBool`, and defaults apply only to unset variables (#80)
- 2026-08-07 Automatic event retention cleanup based on
  `retention_days`, deleting expired events, deliveries, and delivery
  results from each per-webhook event database (#63)
- 2026-08-07 Update golangci-lint to v2.12.2 (Docker image digest in
  `Dockerfile`, release-archive sha256 pins in `script/bootstrap`),
  adopt the canonical `.golangci.yml` (v2 `linters.settings` layout so
  `lll`/`funlen`/`cyclop`/`dupl` thresholds actually apply), and fix
  all newly surfaced lint findings
- 2026-07-07 Adopted scripts-to-rule-them-all: `script/` entrypoints,
  Makefile shims, README Entrypoints section
- 2026-03-25 pin golangci-lint Docker image for linting (#55)
- 2026-03-18 CSRF middleware detects TLS per-request, fixing login over
  plain HTTP and behind reverse proxies (#54)
- 2026-03-17 root path redirects based on auth state (#52)
- 2026-03-17 CSRF protection, SSRF prevention for HTTP delivery targets
  with DNS rebinding defense, and per-IP login rate limiting (#42)
- 2026-03-17 Slack target type for incoming webhook notifications (#47)
- 2026-03-17 Dockerfile absolute paths and static linking (#49);
  absolute dev DATA_DIR default and clarified env docs (#46)
- 2026-03-05 security headers middleware, session regeneration on
  login, request body size limits (#41)
- 2026-03-04 tests for delivery, middleware, and session packages
  (#32); removed globals.Buildarch (#31)
- 2026-03-04 1.0 MVP merge: Webhook/Entrypoint/Target rename, core
  delivery engine with bounded worker pool and circuit breaker,
  parallel fan-out, per-webhook event databases, management UI (#16)
- 2026-03-01 repo brought to REPO_POLICIES standards; TODO.md folded
  into README (#6)

# Future Steps

- Delivery status and retry management UI
- Per-webhook rate limiting in the receiver handler (per-webhook config
  plus handler enforcement; global limits must not apply to receiver
  endpoints)
- Webhook signature verification for GitHub and Stripe HMAC formats
- API key authentication for programmatic access (APIKey model exists;
  Bearer token middleware does not)
- REST API v1
    - CRUD for webhooks, entrypoints, targets
    - event viewing and filtering endpoints
    - event redelivery endpoint
    - OpenAPI specification
- Analytics dashboard: success rates, response times, volume
- A remember-me option at login
- Password change and reset flow
- Later, nice to have
    - email delivery target type
    - SNS and S3 delivery targets
    - data transformations (e.g. webhook to Slack message formatting)
    - JSONL file delivery with periodic S3 upload
    - webhook event search and filtering
    - multi-user with role-based access control