Skip to content

refactor: extract allowlist to lib/ with ALLOWLIST_FILE override#18

Merged
scops merged 2 commits into
mainfrom
refactor/configurable-allowlist
May 10, 2026
Merged

refactor: extract allowlist to lib/ with ALLOWLIST_FILE override#18
scops merged 2 commits into
mainfrom
refactor/configurable-allowlist

Conversation

@scops
Copy link
Copy Markdown
Collaborator

@scops scops commented May 10, 2026

Summary

  • Extracts the sanitize-html allowlist (tags, attributes, schemes, mode) from server.js into lib/allowlist.js.
  • Adds ALLOWLIST_FILE env var: when set, the JSON file at that path is loaded and used instead of the built-in allowlist.
  • Loader (loadAllowlist) validates the file shape and fails fast at startup — malformed JSON, missing file, or non-array allowedTags throws before the server accepts requests, rather than silently falling back.

Why

The original allowlist was inlined in the handler. With it lifted into its own module, different consumers can run the same image with different policies (a strict subset for UGC, a relaxed superset for trusted authoring tools) without forking the codebase or shipping their own build.

The "wholesale replace, no merge with defaults" choice is deliberate: merging surprises operators (you removed iframe from allowedTags but inherited iframe's attributes from defaults). Forcing the override file to be self-contained makes the runtime allowlist trivially auditable.

Test plan

  • npm test — 39/39 (7 new):
    • loadAllowlist returns the frozen default when unset.
    • Reads, parses and applies a custom JSON file.
    • Throws on missing file, malformed JSON, wrong allowedTags type, wrong top-level type.
    • Integration: sets ALLOWLIST_FILE to a relaxed config and hits /validate with <iframe>safe: true confirms the override flows through to sanitize-html.
  • CI green on Node 20/22/24, audit, CodeQL.

Notes

  • The default DEFAULT_ALLOWLIST is Object.freezed so the module can't be mutated at runtime.
  • No version bump in this PR. This is the first of three queued features (allowlist override, rate limiting, SBOM). Once all three land, a single chore: release 2.3.0 PR will bump versions and consolidate the CHANGELOG entries.

Comment thread tests/allowlist.test.js Fixed
@scops scops self-assigned this May 10, 2026
@scops scops merged commit 264911d into main May 10, 2026
6 checks passed
@scops scops deleted the refactor/configurable-allowlist branch May 10, 2026 20:20
@scops scops mentioned this pull request May 10, 2026
4 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants