# Gitea webhook threat model

Status: design gate only. Incoming webhooks are disabled and no webhook is
registered by DevRunbook. Periodic PostgreSQL-backed refresh remains the sole
automatic freshness mechanism for this release.

## Trust boundary

A webhook body, headers, event name, repository identity and delivery ID are
untrusted network input. They may request only the same bounded, read-only
snapshot job that an authorized refresh already creates. They must never carry
forge credentials, select a workspace directly, execute content or mutate a
repository.

## Mandatory controls before enabling an endpoint

- Authenticate the exact raw body with HMAC-SHA-256 and a per-integration
  secret; compare the digest in constant time before parsing JSON.
- Require a signed timestamp within five minutes and a cryptographically
  random delivery ID. Persist `(integration_id, delivery_id)` with a TTL and
  atomically reject replays before enqueueing work.
- Resolve workspace and repository exclusively from the authenticated
  integration and allowlisted remote identity. Never trust workspace IDs or
  callback URLs supplied by the body.
- Limit the raw body before buffering, allowlist push/default-branch and
  repository-change events, validate content type and reject unknown fields.
- Apply independent per-source-IP, per-integration and per-workspace token
  buckets before database work. Return `429` with bounded jitter and never
  bypass the normal queue's deduplication or retry limits.
- Use the existing snapshot preflight and idempotency contract. A delivery may
  enqueue work but cannot force full analysis or create a profile revision.
- Log only a hashed delivery ID, integration ID, event class and safe outcome.
  Never log the signature, raw body, token or repository content.
- Respond with generic errors so signature, tenant and repository existence
  cannot be enumerated. Keep last-known-good snapshots on every failure.

## Required verification gate

The feature stays disabled until integration tests prove valid/invalid
signatures, raw-byte verification, expired/future timestamps, replay races,
body limits, event allowlisting, flood limits, queue deduplication and strict
cross-workspace isolation. Deployment documentation must also cover secret
rotation with an explicitly bounded overlap window and immediate revocation.

This keeps the Gitea integration read-only: webhook registration itself is an
operator action outside DevRunbook, and the callback can only schedule reads.