feat(security): allow named internal hosts with ALLOWED_HOSTS

[ChiragAgg5k]

What does this PR do?

#18 (released in 0.3.5) refuses every host that isn't publicly routable. That's right for Appwrite Cloud, which captures public preview URLs, but it stops self-hosted Appwrite from upgrading: self-hosted captures sites through the internal appwrite service (_APP_WORKER_SCREENSHOTS_ROUTER=http://appwrite), and that name resolves to a private Docker-network address.

This adds ALLOWED_HOSTS, a comma-separated list of exact hostnames, matched case-insensitively, that may resolve privately:

• isAllowedHost(host): allowed if the host is listed, otherwise the existing isPublicHost check.
• assertPublicUrl is renamed assertAllowedUrl, since a listed internal host now passes.
• Both /v1/screenshots and /v1/reports use it for the first URL and for every request the page makes.
• Empty by default, so behaviour is unchanged unless an operator sets it.
• Matching is by exact hostname: listing appwrite doesn't allow 127.0.0.1, 169.254.169.254, or any other private name or address.
• The README has a new Configuration section.

Self-hosted then sets ALLOWED_HOSTS=appwrite on the browser service and can move to the release that includes this.

Out of scope: redirect hops still aren't checked (#20).

Test Plan

• bun test tests/unit: 94 pass. New cases cover parsing, a listed host allowed case-insensitively, other private and metadata hosts still blocked with a list set, public hosts unaffected, and nothing private allowed by default.
• bun run lint (Biome), bun run check (ESLint) and bun run type-check are clean.
• Real server with Chromium, against a page served on localhost:8099:

Server	http://localhost:8099/	http://127.0.0.1:8099/	http://169.254.169.254/	https://example.com
No ALLOWED_HOSTS	400 not publicly routable	—	—	200 image
ALLOWED_HOSTS=localhost	200 image	400	400	200 image

Related

• fix(security): validate browser navigation targets to block SSRF #18, Navigation guard misses redirect hops to private addresses #20
• appwrite-labs/cloud#6236

[github-actions]

Docker Image Stats

Metric	Value
Image Size	494MB
Memory Usage	155.5MiB
Cold Start Time	1.02s
Screenshot Time	.87s

_{Screenshot benchmark: Average of 3 runs on https://appwrite.io}

[hansi-codes]

🟢 Tier S · Ready to merge

The documentation update resolves the outstanding finding without introducing a new defect.

Adds an opt-in ALLOWED_HOSTS list for exact, case-insensitive exceptions to public-host checks. Screenshot and report routes use the new helper, with unit coverage and a configuration example. The README now explicitly documents unchecked redirect hops and recommends outbound network restrictions.

Latest changes: The README qualifies its blocking guarantee and documents the redirect-hop limitation with a recommendation to restrict outbound network access.

Verdict	New comments	Fixed	Still open
✅ Approved	0	1	0

📂 Walkthrough · 5

File	Change
README.md	Documents ALLOWED_HOSTS, a Compose example, and the redirect-hop security limitation.
src/routes/reports.ts	Uses allowed-host checks for initial navigation and intercepted requests.
src/routes/screenshots.ts	Uses allowed-host checks for initial navigation and intercepted requests.
src/utils/ssrf.ts	Parses the environment allowlist and adds hostname and URL checks with explicit exceptions.
tests/unit/ssrf.test.ts	Covers parsing, allowlist matching, and preservation of private-host blocking.

✅ Fixed since the last review · 1

• Mention the redirect limitation in the security guarantees · README.md:51

---

_{Reviewed the commits since 36ba120 · Details · Comment @hansi-codes review to re-run, or mention @hansi-codes with a question.}

[hansi-codes]

🔵 Tier A · Looks good to merge. Summary

[hansi-codes]

🟢 Tier S · Looks good to merge. Summary