htmx-security
Review and harden security for htmx and server-driven web apps. Use when handling user-supplied HTML, escaping or sanitizing fragments, adding CSP, evaluating XSS risk, configuring CSRF or cookies, loading htmx from a CDN, using SRI hashes, accepting hx-* attributes from content, or reviewing htmx request headers and history caching.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- htmx-security
- license
- MIT
- metadata
- { "tags": "htmx,security,xss,csp,frontend", "version": "0.1.0", "category": "Frontend", "displayName": "htmx Security" }
- description
- Review and harden security for htmx and server-driven web apps. Use when handling user-supplied HTML, escaping or sanitizing fragments, adding CSP, evaluating XSS risk, configuring CSRF or cookies, loading htmx from a CDN, using SRI hashes, accepting hx-* attributes from content, or reviewing htmx request headers and history caching.
- compatibility
- Codex, Claude Code, and other Agent Skills-compatible clients.
02 资源文件 2
- 参考文档agents/openai.yaml317 B
- 资产文件assets/icons8-code.svg460 B
03 SKILL.md 正文
htmx Security
Use this skill before shipping htmx features that render user content, accept rich HTML, add third-party scripts, change Content Security Policy, or expose new mutation endpoints.
Threat Model
htmx keeps rendering on the server, but unsafe HTML is still unsafe HTML. A fragment swap can insert scripts, event handlers, dangerous URLs, or htmx attributes that cause requests. Treat every fragment as executable browser surface unless it is escaped or sanitized.
Baseline Rules
- Escape user-supplied text by default.
- Sanitize rich HTML on the server with a strict allowlist.
- Strip or block
hx-*,data-hx-*,hx-on, inline event handlers,script, dangerous URLs, and style features that the product does not explicitly allow. - Keep auth, authorization, and validation on the server.
- Use CSRF protection for same-origin mutations.
- Do not put secrets, privileged object IDs, or authorization decisions in HTML attributes.
- Keep htmx requests same-origin unless CORS, CSRF, cookies, and credentials are deliberately designed.
User Content
Choose one content policy:
| User content type | Policy |
|---|---|
| Plain text | Escape and render as text |
| Markdown | Render through a sanitizer and allow only safe tags/attributes |
| Rich HTML | Sanitize with a narrow allowlist and strip htmx/event/script capabilities |
| Trusted admin HTML | Still sanitize unless the trust boundary is documented and access is tightly controlled |
Do not mark content safe merely because it was stored in the database earlier.
htmx-Specific Risks
- User-controlled
hx-get,hx-post,hx-put,hx-patch,hx-delete, orhx-triggercan create unintended requests. - User-controlled
hx-onor inline handlers can execute JavaScript. - User-controlled
hx-valscan smuggle unexpected parameters. - Fragment responses can replace more of the page than intended if targets are broad.
- History caching can retain sensitive HTML on the client.
Use hx-history="false" on sensitive pages or containers that should not be stored in htmx history cache.
CSRF And Cookies
- Prefer the framework's standard CSRF mechanism.
- Configure htmx to send the CSRF header once in the base layout or startup script.
- Keep CSRF tokens out of logs and analytics.
- Use
Secure,HttpOnly, andSameSitecookie settings appropriate to the app. - Avoid cross-site htmx mutations unless the app has a clear credential policy.
CDN And Script Loading
Prefer vendored static assets for reproducibility. If loading htmx or extensions from a CDN:
- pin the exact version;
- include Subresource Integrity where possible;
- set
crossoriginwhen required by SRI; - document why CDN loading is acceptable for the app;
- monitor version changes deliberately rather than floating to latest.
Content Security Policy
Design CSP around the actual frontend stack:
- htmx can work with a strict CSP when inline scripts and unsafe eval are avoided.
- Inline event handlers,
hx-on, Alpine default builds, and_hyperscriptcan require looser policies unless replaced with CSP-compatible patterns. - Start with report-only mode for existing apps, then tighten.
- Include reporting endpoints only when someone reviews reports.
- Test swapped fragments under the final CSP, not just the initial page load.
Review Checklist
- Are all mutation endpoints protected by auth, authorization, and CSRF?
- Does every endpoint re-check permissions server-side?
- Are user values escaped in fragments and full pages?
- Is any rich content sanitized with an allowlist?
- Can user content inject
hx-*,hx-on, event handlers, scripts, or dangerous URLs? - Are sensitive fragments excluded from htmx history cache?
- Are third-party scripts pinned and integrity-checked?
- Does CSP match Alpine,
_hyperscript, and htmx usage? - Do tests cover both htmx and non-htmx paths?
Testing Ideas
- Submit text containing HTML tags and confirm it renders as text.
- Submit sanitized rich content with attempted event handlers and htmx attributes.
- Attempt unauthorized htmx mutations directly with forged headers.
- Verify login redirects do not get swapped into small targets.
- Run browser checks with CSP enabled and inspect violations.
Avoid
- Do not rely on htmx headers as proof of trust.
- Do not trust hidden inputs,
hx-vals, or client-side state for authorization. - Do not allow user-authored htmx attributes in normal rich content.
- Do not loosen CSP globally to fix one component without documenting the tradeoff.
- Do not expose JSON or HTML endpoints with different authorization assumptions.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.