Files
StarPunk/docs/design/v2.7.0/2026-11-03-webmention-spec-compliance.md
PhilandClaude Opus 5.5 0640730416 feat: Pin webmention connections; re-send when responses change (v2.7.2)
- Connect to the address that passed the SSRF check (Host header and SNI
  carry the hostname, so TLS still verifies it), closing the DNS rebinding
  gap (spec 4.5). The webmention POST uses the same path.
- Treat a change in the responses a note shows as an update and re-send its
  webmentions (spec 3.1.4), from validation and from admin moderation.
  Unchanged re-validations send nothing, so there is no ping-pong.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 09:01:38 -07:00

3.4 KiB

v2.7.0: Webmention W3C compliance

Review of StarPunk's Webmention support against the W3C Recommendation (https://www.w3.org/TR/webmention/, 12 January 2017), and the changes made. v2.6.8 and v2.6.9 fixed the bugs that stopped webmentions working at all.

Sending

Section Requirement Change
3.1.2 Link header with rel=webmention first (MUST) RFC 8288 parsing: several links per header, several headers, rel in any position, token list, case-insensitive
3.1.2 Then first <link>/<a> rel=webmention in document order (MUST) Single pass over link and a in document order; rel token match; elements without href skipped
3.1.2 Relative URL resolved against target; empty href is the target; query kept (MUST) urljoin against the final URL after redirects
3.1.2 Follow redirects safe_get follows up to 10, checking each hop
3.1.2 User-Agent with "Webmention" (MAY) StarPunk/<version> Webmention (+site)
3.1.3 Form-encoded POST; any 2xx success (MUST) Unchanged. Redirects not followed (httpx turned 301/302 POST into GET); 429 retried
3.1.4 Re-discover endpoint on update (MUST) Discovery cache removed
3.1.4 Re-send to previously sent targets, including removed links (SHOULD) previous_targets() from the queue, plus removed links; not capped
3.1.5 Deleted post returns 410 (SHOULD), tombstone (SHOULD) public.note aborts 410 for soft-deleted notes and hard-deleted notes that sent webmentions; 410.html
3.1.5 Re-send on delete (SHOULD) requeue_previous_webmentions(); for a hard delete the rows are detached (source_note_id = NULL) first, since the foreign key cascades. Also on undelete

Receiving

Section Requirement Change
3.2 202 for async processing (MUST) Unchanged
3.2.1 Valid http(s) URLs; source ≠ target; 400 on error (MUST) Unchanged
3.2.1 Target is a valid resource (SHOULD) Only published notes; others 400
3.2.1 Fragment ignored Stripped before storing (no duplicate rows)
3.2.2 GET source, follow redirects, limit redirects safe_get
3.2.2 Accept header (SHOULD) Added
3.2.2 Exact match of target, per media type (MUST) HTML: every link attribute (lxml iterlinks) resolved against the final URL; JSON: any string value; text/*: substring; other types: no match. Fragments ignored
3.2.4 Update existing data; 410 / no link removes it (SHOULD) Unchanged in effect. Moderation decisions kept on update; transient errors keep a valid mention

Security (section 4)

  • 4.1 XSS: author URL/photo must be http(s) (v2.6.9); snippets re-sanitized after truncation; Mentions list uses striptags.
  • 4.2 / 4.5: safe_get checks every redirect hop, checks all getaddrinfo addresses, blocks private, loopback, link-local, multicast, reserved, unspecified, CGNAT, 0.0.0.0/8 and IPv4-mapped forms; 1 MB and 10 s total limits.
  • 4.3: endpoint URL checked before POST, no redirects followed.

Known limits

  • Homepage mentions are refused rather than stored.
  • Discovery does not apply HTTP cache headers (5.3); targets are only fetched when a note is created, edited or deleted.
  • The 410 page is a generic tombstone without microformats.
  • error rows (unexpected failures) are not retried automatically.

Tests

tests/test_webmention_spec.py (section-numbered), tests/test_webmention_worker.py.