# Security

## Credentials

- Bitbucket clone/fetch tokens: `BITBUCKET_USERNAME`, `BITBUCKET_TOKEN` (environment variables)
- Webhook HMAC secret: `BITBUCKET_WEBHOOK_SECRET` (must match Bitbucket webhook configuration)

## Webhook signature validation (TW-20)

`POST /webhooks/bitbucket` validates the `X-Hub-Signature` header:

- Algorithm: HMAC-SHA256 over the **raw request body**
- Header format: `sha256=<hex>`
- Comparison uses constant-time equality

When `ENVIRONMENT=local` and `BITBUCKET_WEBHOOK_SECRET` is empty, verification is skipped (local testing only). In all other cases, invalid or missing signatures return **401**.

## Operational practices

- Store secrets in environment variables or a secret manager; never commit `.env`
- Rotate workspace access tokens every 90 days
- Use HTTPS for webhook URLs in production
- Sandbox repository clone and diff operations with resource limits (git runner timeouts)