Security Model
Every trust boundary Sparrow crosses – inbound API, outbound delivery, and data at rest – and what protects it. For envelope encryption at rest and outbound delivery signing, see Architecture: Encryption at Rest and Verifying Webhook Signatures. For TLS, SSO, and per-user login in front of Sparrow, see Securing Sparrow.
API Authentication
Section titled “API Authentication”The master key (SPARROW_API_KEY) or a per-person access token gates every
inbound /v1 request. Credentials travel in X-API-Key or
Authorization: Bearer, never a query parameter – URLs get logged by
proxies, kept in browser history, and leaked via Referer. Key and token
comparison is constant-time, so a wrong guess takes the same time regardless
of how many characters match, defeating timing side-channel attacks.
Empty SPARROW_API_KEY disables auth entirely – intentional for local dev.
With SPARROW_ENVIRONMENT=production, the server refuses to boot without a key, so
this can’t ship silently misconfigured.
Access tokens
Section titled “Access tokens”Named, stored credentials that can be created, listed, and individually revoked. See Access: Tokens and Invites for the operational guide; this section covers the implementation.
- Hashing. Secrets carry 256 random bits; only a SHA-256 hash is stored. The plaintext is returned once, in the creation response.
- Prefixes. Sparrow tokens start with
sparrow_tk_; invite secrets withsparrow_inv_. The prefixes make leaked secrets easy to spot in log scans and secret-scanning tools. - Scopes. A token is either tenant-wide (nil scope – same power as the
master key) or pinned to one consumer (non-nil scope – portal API only,
same allow-list as portal tokens). Consumer-scoped tokens get 403 on
/v1; full-access tokens get 403 on/portal/api. - Cache. Successful lookups are cached for 30 seconds to avoid hitting the database on every request. Revocation clears the cache synchronously on the revoking instance; other instances honour it when their cache entry expires (within 30 seconds).
last_used_at. Updated at most once per minute per token to reduce write load.- 401 reasons. On failure, the JSON body includes a
reasonfield:missing(no credential),invalid(unknown key or token),expired, orrevoked. - 503 on DB outage. If the token store is unreachable, the server returns
503 Service UnavailablewithRetry-After: 5, not401. Browsers keep their credential and retry. The master key (a root key checked in memory) still works without the database. - Invites. A single-use, expiring secret redeemed at
POST /invite/redeem(no auth required – the invite is the credential). Redeeming creates a token; unknown, expired, cancelled, and used invites all return400 invalid_invite.
Portal tokens
Section titled “Portal tokens”A portal token is a consumer-scoped access token (see above), minted with
POST /v1/tokens and a consumer by the master key or a tenant-wide token,
and returned with a ready-made portal_path for the embeddable
consumer portal. Minting,
external_id reuse and lifetimes are covered in
Access: Portal links.
Two storage details differ from other tokens: a token minted with an
external_id also keeps its secret, envelope-encrypted with the keyring and
deleted on revocation, so the same link can be returned again; and the portal
can carry the token in the /portal#token=... URL fragment, which browsers
never send to the server, so it stays out of access logs.
A portal token authorizes exactly: everything under its own consumer’s routes
except pushing or re-pushing events (events:rePush, repush-jobs,
prepare_repush) and minting further tokens, plus the read-only
helpers the portal UI needs (event-type catalog, template functions, server
capabilities, template dry-run). The portal calls these through the single /portal/api/ gateway
prefix — the consumer is carried by the token, not the URL, so cross-consumer
access is structurally impossible and event injection, token minting, other
consumers, global routes, and admin operations all return 401/403.
Retrying the consumer’s own deliveries is allowed unless the server runs
with SPARROW_PORTAL_RETRY=false, which refuses the retry calls and
prepare_retry with 403.
Behind the gateway, every /v1/consumers/{consumer}/... route also checks that
the resource it names belongs to that consumer: a webhook, subscription,
delivery, delivery’s attempts, alert config or batch job of another consumer
answers 404, so a leaked id from another consumer reveals nothing. Batch jobs
snapshotted from an all-consumers list (the operator’s “all consumers” view)
are reachable only with tenant-wide credentials, never with a portal token.
SSRF Protection
Section titled “SSRF Protection”Sparrow makes outbound HTTP requests to user-supplied URLs – the classic server-side request forgery surface. Every URL is checked at three points:
- Registration – only
http/httpsschemes; well-known internal hostnames (localhost,*.internal,*.local, cloud metadata hosts) are rejected outright; everything else is resolved and every returned IP is checked against the blocklist, not just the literal host string. - Every redirect – each redirect target is re-validated before it is followed, so a webhook can’t register a public URL that 302s to an internal one. Redirect chains are capped at 10 hops.
- Connection time – the resolved IP is checked again immediately before the TCP connection is opened, on every delivery. A DNS record that changes after registration (DNS rebinding) still can’t steer a delivery to a blocked address.
Blocked ranges: loopback (127.0.0.0/8, ::1), private (10/8,
172.16/12, 192.168/16), link-local (169.254.0.0/16 – covers the
169.254.169.254 cloud metadata endpoint), CGNAT (100.64.0.0/10, RFC
6598), and IETF special-use/multicast/reserved ranges (RFC 6890).
TLS verification
Section titled “TLS verification”Deliveries verify the receiver’s TLS certificate. A webhook can opt out with
http_config.verify_ssl: false, for trusted internal endpoints with
self-signed certificates; it defaults to true, and the SSRF checks above
still apply to opted-out webhooks.
Go’s certificate verification checks no revocation: no CRLs, no OCSP, no
browser blocklists. Sparrow adds two checks after it, on every outbound
client that verifies TLS (pkg/safetransport, a stdlib-only module other Go
programs can import).
Certificate revocation
Section titled “Certificate revocation”Each intermediate in a receiver’s chain is checked against the CRL its
issuer publishes (SPARROW_TLS_REVOCATION, default soft). Leaf
certificates are not checked: their CRLs are large and change often, and the
compromise this guards against is a CA key, which is what intermediates
carry.
- When CRLs are downloaded. The first delivery whose chain needs a CRL
downloads it and waits for it: at most 5s in total per connection, however
many intermediates the chain has. A download still running after that
finishes in the background, and that connection treats the CRL as
unavailable (allowed in
soft). Each instance keeps its CRLs in memory. Once a CRL is older thanSPARROW_CRL_MAX_AGE(default6h), the next delivery that uses it refreshes it in the background and still uses the cached copy. A CRL past its ownnextUpdateis downloaded again before use. Nothing runs on a schedule, and an idle instance downloads nothing. - Refreshing now. When a CA revokes an intermediate and you don’t want to
wait for the max age,
POST /v1/tls/crls:refreshasks every instance to download its CRLs, through a PostgresNOTIFY. One request a minute per server.GET /v1/tls/crlsshows what the answering instance has cached and any download errors. - When a CRL can’t be used (unreachable, bad signature, expired),
softallows the connection and records the error, andhardrefuses it. A certificate listed on an expired CRL is still refused: revocation is permanent. Intermediates without an http(s) CRL address, typical of private CAs, are not checked in either mode. - SSRF. CRL addresses come from certificates a remote server sends, so downloads go through the same network policy as deliveries. The chain is checked from the root down and stops at the first revoked intermediate, so a CRL address written by a revoked CA, such as one an attacker put in a certificate signed with a stolen key, is never fetched.
A revoked chain fails the delivery with tls_error, which is not retried.
Compromised CA keys
Section titled “Compromised CA keys”A separate check refuses chains containing an EC key whose private key is
below 256, or its negation: the eMudhra intermediates of October 2026
(Mozilla bug 2083449).
It needs no network access, so it also protects with
SPARROW_TLS_REVOCATION=off and covers the AI provider and documentation
fetches, which skip the CRL check. It targets that incident, not weak keys in
general.
HTTP Hardening
Section titled “HTTP Hardening”Defense-in-depth headers on every API and UI response:
| Header | Value | Stops |
|---|---|---|
X-Content-Type-Options |
nosniff |
Browser MIME-sniffing a JSON response as HTML – reflected XSS |
X-Frame-Options |
DENY (omitted on /portal paths, which allow framing) |
Clickjacking – the admin UI is never legitimately framed; the portal is designed for iframe embedding |
Referrer-Policy |
strict-origin-when-cross-origin |
Leaking consumer/webhook IDs in URLs to an external Referer |
Permissions-Policy |
interest-cohort=() |
FLoC / Topics API tracking |
Content-Security-Policy |
default-src 'self'; script-src 'self' 'sha256-...' ...; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; img-src 'self' data:; connect-src 'self' |
Loading any script, style, or image from a non-Sparrow origin other than the UI’s Google Fonts. When the embedded UI is built, script-src uses SHA-256 hashes of the SPA’s inline scripts instead of 'unsafe-inline'; the fallback to 'unsafe-inline' applies only when the UI is not embedded (API-only deploys). Portal paths add frame-ancestors *; non-portal paths add frame-ancestors 'none'. Applies only when Sparrow serves the UI; a separately hosted UI gets whatever headers its static host sets |
Two more request-level controls:
- Body size cap: every request body is capped at
SPARROW_MAX_BODY_BYTES(default 5 MiB) – bounds memory use against oversized payloads before they’re read. Values below 1 MiB are rejected at startup. API requests are also limited to 1 MiB each (event-type import: 5 MiB). - Per-webhook rate limiting: optional leaky-bucket
http_config.rate_limit_rpsper webhook throttles outbound delivery – protects the receiver from being hammered. (It does not protect Sparrow’s own inbound API; see the note under API Authentication.)
Webhook Secret Rotation
Section titled “Webhook Secret Rotation”POST .../webhooks/{id}:rotateSecret replaces the HMAC signing secret at
once. There is no overlap window: every attempt made after the rotation,
retries of older deliveries included, is signed with the new secret only, and
a receiver still verifying with the old one rejects them. Update the receiver
promptly, or pause the webhook, rotate, update the receiver, and resume
(held deliveries are retried by hand). Rotation does not change an Ed25519
signing key.
Metrics Endpoint
Section titled “Metrics Endpoint”GET /metrics serves Prometheus metrics with no authentication, like
/health. Its labels include the host names and ports of webhook receivers
(from the outbound HTTP client metrics), webhook counts by health and status,
queue depths, and database pool statistics. If that is sensitive, set
SPARROW_METRICS_ENABLED=false or block /metrics at the reverse proxy and
scrape it from inside the network.
Credentials in the Browser
Section titled “Credentials in the Browser”The operator UI keeps the credential it signs in with (an access token from
an invite or from exchanging the master key, or a pasted credential) in
localStorage (sparrow_api_key), and the portal keeps its consumer token
there too, so a session survives restarts. Any script running on the UI’s
origin could read it; the strict Content-Security-Policy above, which allows
only Sparrow’s own scripts, is what stands between the two. Signing out
removes it and revokes tokens the browser created. Use a separate origin for
the UI if other content is served next to it.
The portal (/portal paths) is sent with frame-ancestors * so it can be
embedded in an iframe on any site; the operator UI is sent with
frame-ancestors 'none' and X-Frame-Options: DENY. To restrict who can
frame the portal, have the reverse proxy replace frame-ancestors * in that
header with your own list, keeping the rest of the policy as Sparrow sent it.
Secret Masking in Responses
Section titled “Secret Masking in Responses”The plaintext webhook secret (whsec_...) is returned exactly once, in the
webhook-creation response – copy it down then. Every later read (list, get,
update) returns only its shape: the whsec_ prefix plus one • per secret
character. The stored secret is decrypted server-side solely to compute that
mask; the plaintext never appears in any response again. If a stored secret
can’t be decrypted, the response degrades to a fixed •••••• instead of
erroring or revealing which webhooks are affected.
Secret headers are stricter: their values never round-trip at all, masked
or otherwise. Every configured header comes back as a flat ••••••
regardless of the original value’s length – only the header name is real,
so a reader can’t even infer secret length from the mask.
A webhook with no secret or secret headers simply returns empty fields – distinguishable from the fixed mask a decryption failure produces.
Webhook URLs in Logs and Traces
Section titled “Webhook URLs in Logs and Traces”Webhook URLs often carry credentials outside the user:pass@ part: in the
path (Slack’s /services/T…/B…/<secret>, Discord’s /api/webhooks/<id>/<token>)
or the query string (?token=). Sparrow’s logs and trace spans therefore
record only the scheme and host (https://hooks.slack.com/…); this includes
the url.full attribute of each delivery’s HTTP span, so secrets never reach
your OTLP backend. Delivery error messages (e.g. connection refused) have the
URL reduced the same way.
Use the webhook ID to find the endpoint; the full URL is still available
through the API to callers with access.
Consumer Isolation
Section titled “Consumer Isolation”Resources are namespaced by consumer – one integration’s webhooks,
events, and deliveries are invisible to another’s in every list and lookup.
The global list routes (GET /v1/webhooks, /v1/deliveries, etc.) can span
consumers, but never cross the instance’s data boundary.
Production Config Checklist
Section titled “Production Config Checklist”What Sparrow enforces before the server will boot, and what you should set:
| Variable | Requirement |
|---|---|
SPARROW_ENCRYPTION_KEYS |
Always required. Comma-separated <key-id>=<64-char-hex-key> entries. |
SPARROW_ENCRYPTION_PRIMARY_KEY_ID |
Always required. Selects the primary key for new encryption. |
SPARROW_ENVIRONMENT |
Set to production (any case). Any other value runs as development, without the checks in this table. |
SPARROW_API_KEY |
Required, at least 32 characters, when SPARROW_ENVIRONMENT=production. Empty is fine for local dev only. |
DATABASE_URL |
Always required. |
SPARROW_MAX_BODY_BYTES |
Optional, default 5 MiB. Values below 1 MiB are rejected at startup. |
SPARROW_ALLOW_PRIVATE_NETWORKS |
Leave unset (false) unless your webhook targets live on your own private network – true disables most SSRF network checks (cloud metadata stays blocked; only SPARROW_ALLOWED_NETWORKS can reach it). |
SPARROW_METRICS_ENABLED |
Optional, default true. Serves Prometheus metrics at /metrics, unauthenticated; labels include receiver host names. Firewall it or set to false if the data is sensitive. See Metrics Endpoint. |
SPARROW_EVENT_RETENTION_DAYS |
Optional, default 0 (keep forever). Purges events and their deliveries older than N days – event payloads are stored in plaintext, so pair a retention window with storage-layer encryption when payloads are sensitive. See Securing Sparrow. |