Network Working Group K. Dunglas, Ed. Internet-Draft Les-Tilleuls.coop Intended status: Standards Track 11 August 2026 Expires: 12 February 2027 The Mercure Protocol draft-dunglas-mercure-08 Abstract Mercure provides a common publish-subscribe mechanism for public and private web resources. It pushes any web content to web browsers and other clients over a single long-lived HTTP connection, avoiding polling and its associated latency and power cost. Mercure is especially useful for delivering real-time updates of resources served through sites and web APIs to web and mobile applications, and can also be used as a general-purpose publish-subscribe system. Subscription requests are relayed through hubs, which validate them. When new or updated content becomes available, hubs check whether subscribers are authorized to receive it and then distribute it. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 12 February 2027. Copyright Notice Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Dunglas Expires 12 February 2027 [Page 1] Internet-Draft Mercure August 2026 Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Subscription . . . . . . . . . . . . . . . . . . . . . . . . 5 4. Matcher Types . . . . . . . . . . . . . . . . . . . . . . . . 9 4.1. Exact Matching . . . . . . . . . . . . . . . . . . . . . 10 4.2. URL Pattern . . . . . . . . . . . . . . . . . . . . . . . 10 4.3. Summary of Matcher Types . . . . . . . . . . . . . . . . 11 5. Publication . . . . . . . . . . . . . . . . . . . . . . . . . 11 6. Authorization . . . . . . . . . . . . . . . . . . . . . . . . 14 6.1. Presenting the Access Token . . . . . . . . . . . . . . . 16 6.1.1. Authorization HTTP Header . . . . . . . . . . . . . . 16 6.1.2. Cookie . . . . . . . . . . . . . . . . . . . . . . . 17 6.2. Error Responses . . . . . . . . . . . . . . . . . . . . . 18 6.3. Token Validation . . . . . . . . . . . . . . . . . . . . 19 6.4. Authorization Details . . . . . . . . . . . . . . . . . . 20 6.5. Publishers . . . . . . . . . . . . . . . . . . . . . . . 21 6.6. Subscribers . . . . . . . . . . . . . . . . . . . . . . . 22 6.7. Topic Matcher List . . . . . . . . . . . . . . . . . . . 23 6.8. Payloads . . . . . . . . . . . . . . . . . . . . . . . . 24 7. Reconnection, State Reconciliation, and Event Sourcing . . . 25 8. Active Subscriptions . . . . . . . . . . . . . . . . . . . . 28 8.1. Subscription Events . . . . . . . . . . . . . . . . . . . 28 8.2. Subscription API . . . . . . . . . . . . . . . . . . . . 30 9. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 35 9.1. Hub Discovery . . . . . . . . . . . . . . . . . . . . . . 35 9.2. Protected Resource Metadata . . . . . . . . . . . . . . . 37 9.3. Topic Discovery . . . . . . . . . . . . . . . . . . . . . 38 9.3.1. Content Negotiation . . . . . . . . . . . . . . . . . 39 10. Encryption . . . . . . . . . . . . . . . . . . . . . . . . . 40 11. Using HTTP . . . . . . . . . . . . . . . . . . . . . . . . . 41 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 41 12.1. Well-Known URIs Registry . . . . . . . . . . . . . . . . 41 12.2. Link Relation Types Registry . . . . . . . . . . . . . . 41 12.3. OAuth Protected Resource Metadata Registry . . . . . . . 42 12.4. HTTP Field Name Registry . . . . . . . . . . . . . . . . 42 12.5. Mercure Topic Matcher Types Registry . . . . . . . . . . 43 12.6. Mercure Actions Registry . . . . . . . . . . . . . . . . 44 13. Security Considerations . . . . . . . . . . . . . . . . . . . 44 13.1. Token Validation . . . . . . . . . . . . . . . . . . . . 45 13.2. Server-Sent Events Field Injection . . . . . . . . . . . 46 Dunglas Expires 12 February 2027 [Page 2] Internet-Draft Mercure August 2026 13.3. Reserved Hub Namespace . . . . . . . . . . . . . . . . . 46 13.4. Authorization on Event Replay . . . . . . . . . . . . . 47 13.5. Subscriber Identifier Assignment . . . . . . . . . . . . 47 13.6. Private Update Audience . . . . . . . . . . . . . . . . 47 13.7. URL-Pattern Denial of Service . . . . . . . . . . . . . 48 13.8. Payload Privacy . . . . . . . . . . . . . . . . . . . . 48 13.9. Topic Normalization . . . . . . . . . . . . . . . . . . 48 13.10. Resource Limits . . . . . . . . . . . . . . . . . . . . 49 13.11. Hub Trust . . . . . . . . . . . . . . . . . . . . . . . 49 13.12. Protected Resource Metadata and Authorization Server Selection . . . . . . . . . . . . . . . . . . . . . . . 49 13.13. Bearer Tokens and Sender Constraint . . . . . . . . . . 49 13.14. Publish Request Replay . . . . . . . . . . . . . . . . . 50 13.15. JWE Algorithms and Replay . . . . . . . . . . . . . . . 50 14. Privacy Considerations . . . . . . . . . . . . . . . . . . . 50 15. Implementation Status . . . . . . . . . . . . . . . . . . . . 50 15.1. Mercure.rocks Hub . . . . . . . . . . . . . . . . . . . 51 15.2. Freddie . . . . . . . . . . . . . . . . . . . . . . . . 52 15.3. Ilshidur/node-mercure . . . . . . . . . . . . . . . . . 53 15.4. Symfony . . . . . . . . . . . . . . . . . . . . . . . . 53 15.5. API Platform . . . . . . . . . . . . . . . . . . . . . . 54 15.6. Laravel Mercure Broadcaster . . . . . . . . . . . . . . 55 15.7. dart_mercure . . . . . . . . . . . . . . . . . . . . . . 56 15.8. pymercure . . . . . . . . . . . . . . . . . . . . . . . 57 15.9. Amphp Mercure Publisher . . . . . . . . . . . . . . . . 58 15.10. Java Library for Mercure . . . . . . . . . . . . . . . . 59 15.11. Yii 2 Mercure behavior . . . . . . . . . . . . . . . . . 59 15.12. GitHub Action for Mercure . . . . . . . . . . . . . . . 60 15.13. Other Implementations . . . . . . . . . . . . . . . . . 61 16. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 61 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 61 17.1. Normative References . . . . . . . . . . . . . . . . . . 61 17.2. Informative References . . . . . . . . . . . . . . . . . 64 Appendix A. Changes from Pre-Standardization Deployments . . . . 67 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 68 1. Introduction Mercure is a protocol for pushing updates of web resources to clients over HTTP. It builds on Server-Sent Events [HTML] for delivery and on JSON Web Signatures [RFC7515] for authorization, so that it can be implemented on top of existing HTTP infrastructure and consumed natively by web browsers. Dunglas Expires 12 February 2027 [Page 3] Internet-Draft Mercure August 2026 Publishers send updates to a hub. Subscribers open a long-lived HTTP connection to the hub and declare, using topic matchers, which topics they want to receive. The hub checks authorization and dispatches matching updates, including updates marked as private that only authorized subscribers may receive. This document specifies the subscription and publication interfaces, the topic matcher types, the OAuth 2.0-based authorization model, reconnection and state reconciliation, active-subscription tracking, discovery, and update encryption. Some normative references of this document are dated snapshots (Review Drafts) of WHATWG Living Standards. Conformance is evaluated against the cited snapshots; later changes to those standards do not automatically apply to this protocol. 2. Terminology The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. * Topic: The unit to which one can subscribe for changes. The topic is identified by a string that can be an IRI [RFC3987]. Topic strings MUST be valid UTF-8 [RFC3629] and MUST NOT contain C0 (U+0000–U+001F) or C1 (U+0080–U+009F) control characters, U+007F (DEL), or Unicode format characters (general category Cf [UNICODE], such as the bidirectional and zero-width controls), which are invisible and enable identifier spoofing. Character classifications are those of the Unicode version cited in [UNICODE]; hubs MAY also reject characters that later Unicode versions assign to general category Cf. * Canonical topic: The first topic value of an update; the primary identifier of the updated resource. * Alternate topic: Any topic value of an update other than the canonical topic. An update is dispatched to subscribers matching either the canonical topic or an alternate topic (see Section 5). * Update: The message containing the updated version of the topic. An update can be marked as private; in that case, it MUST be dispatched only to subscribers allowed to receive it. * Topic matcher: An expression matched against one or more topics, depending on the matcher type. * Topic matcher type: The kind of a matching expression, which determines how the expression is interpreted. This document defines two matcher types, exact and urlpattern; others can be registered (see Section 4). Dunglas Expires 12 February 2027 [Page 4] Internet-Draft Mercure August 2026 * Publisher: An owner of a topic. Notifies the hub when the topic feed has been updated. As in almost all pub-sub systems, the publisher is unaware of the subscribers, if any. Other pub-sub systems might call the publisher the "source". Typically a site or a web API, but it can also be a web browser. * Subscriber: A client application that subscribes to real-time updates of topics using topic matchers. Typically a web or a mobile application, but it can also be a server. * Subscription: A topic matcher used by a subscriber to receive updates. A single subscriber can have several subscriptions by providing several topic matchers. * Hub: A server that handles subscription requests and distributes content to subscribers when the corresponding topics have been updated. A hub MAY implement its own policies on who can use it. The hub is an OAuth 2.0 protected resource [RFC6749]. * Access token: The credential a client presents to the hub to prove authorization, carried as a JWT [RFC7519] following the JWT access token profile [RFC9068]. * Resource identifier: The OAuth 2.0 resource identifier of the hub, used as the audience (aud) of access tokens and advertised through protected resource metadata [RFC9728]. * Authorization server: An OAuth 2.0 authorization server [RFC6749] that issues access tokens for the hub. Its use is OPTIONAL; access tokens MAY be self-issued. * Authorization details: The authorization_details claim [RFC9396] carried in an access token, expressing which actions a client may perform on which topics. 3. Subscription The subscriber subscribes to a URL exposed by a hub to receive updates from one or more topics. To subscribe, the client opens an HTTPS connection to the hub's subscription URL (advertised by the publisher; see Section 9) following the Server-Sent Events specification [HTML]. Hubs MUST support the GET HTTP method, which is the method used by EventSource clients [HTML]. Hubs MAY also accept any other safe [RFC9110] method whose semantics allow the topic matcher parameters to be carried in the request body instead of the query component — notably the QUERY method [RFC10008] — so that subscribers can send topic matcher lists too large for the URI length limits of intermediaries. When the parameters are carried in the request body, they MUST be encoded as application/x-www-form- urlencoded [URL], and the reserved-namespace rule and value constraints below apply identically to the body-decoded names and values. Dunglas Expires 12 February 2027 [Page 5] Internet-Draft Mercure August 2026 A request carrying such a body MAY also carry parameters in the query component. The hub MUST then take the union of the two: every name/ value pair from the query component and every pair from the body, as if they had all appeared in one component. This applies to the topic matcher parameters and to last_event_id (see Section 7) alike, so a subscriber whose matcher list only fits in the body can still send its cursor there. A subscription is created for every matcher parameter in the union, so the two components need no precedence rule between them. last_event_id is single-valued: if it appears in both, the hub MUST use the value from the query component, and the Last- Event-ID HTTP field still takes precedence over either (see Section 7). The connection SHOULD use HTTP version 2 or higher to leverage multiplexing and other performance-related features. The subscriber specifies the topics to receive updates from using topic matcher query parameters. The parameter name encodes the matcher type: the bare match parameter selects the default exact matcher type, and a match_ parameter selects the named matcher type — for example, match_urlpattern selects the urlpattern matcher type, and match_exact is the explicit spelling of the default. The suffix MUST be the matcher type name in its canonical form as defined in Section 4. A request MAY contain several such parameters, in any combination. See Section 4. These parameters select which topics the subscriber receives; they do not by themselves grant access to private updates, which is governed by the access token (see Section 6). This mirrors the topic matcher list of authorization details (see Section 6.7), where the match_type member is optional and defaults to exact: omitting it there is equivalent to using the bare match parameter here. The query component of the subscription URL MUST be parsed into name/ value pairs using the application/x-www-form-urlencoded parsing algorithm of [URL] (the algorithm implemented by URLSearchParams and used by EventSource). The reserved-namespace rule and the value constraints below apply to the percent-decoded parameter names and values. A parameter name given without a value is equivalent to that name with an empty value. Clients MUST percent-encode any character in a matcher name or value that application/x-www-form-urlencoded serialization would encode — notably &, =, +, ;, and % — as URLSearchParams does; this keeps parsing unambiguous across implementations (some form-urlencoded parsers treat a raw ; as a delimiter or reject a stray %). Dunglas Expires 12 February 2027 [Page 6] Internet-Draft Mercure August 2026 The names of topic matcher query parameters are case-sensitive. A request using a parameter name in the reserved match namespace (a name equal to match, or beginning with match under an ASCII case- insensitive comparison) that does not correspond to a matcher type supported by the hub (see Section 4) MUST be rejected with a 400 "Bad Request" HTTP status code. This deliberately reserves the whole match prefix: unrelated query parameters whose names begin with match cannot be used on the subscription URL, and a misspelled matcher type — or a registered matcher type the hub does not implement — fails loudly instead of being silently ignored. The value of each topic matcher query parameter MUST be valid UTF-8 [RFC3629] and MUST NOT contain C0 (U+0000–U+001F) or C1 (U+0080–U+009F) control characters, U+007F, or Unicode format characters (general category Cf [UNICODE]). A parameter value that is not valid for its matcher type (for example, a match_urlpattern value that is not a well-formed URL Pattern) is equally invalid. Requests violating any of these constraints MUST be rejected with a 400 "Bad Request" HTTP status code. The subscriber receives updates for all topics matching at least one topic matcher according to the matcher type rules. To mitigate resource exhaustion, hubs SHOULD apply implementation- defined maximums to the number of topic matcher query parameters in a single request and to the length of each matcher's pattern. Requests exceeding any such limit MUST be rejected with a 400 "Bad Request" HTTP status code. A subscription is created for every topic matcher query parameter present in the request. Hubs MAY deduplicate subscriptions that have identical matcher type and pattern. See Section 8.1. Because subscription connections are long-lived, hubs SHOULD also apply implementation-defined limits to the number of concurrent connections held by a single client (for example, per source address or per token subject) and in total, and MAY reject further connection attempts with a 429 "Too Many Requests" HTTP status code [RFC6585]. The EventSource JavaScript interface [HTML] MAY be used to establish the connection. Any other appropriate mechanism, including but not limited to readable streams [streams] and XMLHttpRequest [xhr] (used by popular polyfills), MAY also be used. Web browsers enforce the CORS protocol [FETCH] on cross-origin EventSource connections. Hubs serving browser-based subscribers on other origins MUST send the appropriate CORS response headers. When the connection carries credentials (such as the cookie defined in Section 6.1.2), the Access-Control-Allow-Origin response header MUST Dunglas Expires 12 February 2027 [Page 7] Internet-Draft Mercure August 2026 NOT be the * wildcard and MUST NOT be reflected from arbitrary request origins: it MUST be restricted to an explicit allowlist of trusted origins, and the hub MUST also send Access-Control-Allow- Credentials: true. Reflecting arbitrary origins on a credentialed endpoint would allow any site visited by the subscriber to read updates using the subscriber's cookie. The hub sends updates to the subscriber for topics matching the provided topic matchers. If an update is marked as private, the hub MUST NOT dispatch it to subscribers not authorized to receive it. See Section 6. The hub MUST send these updates as text/event-stream-compliant events [HTML]. Event streams are long-lived responses and interact poorly with intermediaries that buffer responses or terminate idle connections. When no update has been dispatched for an implementation-defined period, hubs SHOULD send an SSE comment line (a line starting with : [HTML]) as a keep-alive, and deployments SHOULD configure intermediaries not to buffer event streams. The data property MUST contain the topic's new version. It MAY be the full resource or a partial update in formats such as JSON Patch [RFC6902] or JSON Merge Patch [RFC7396]. All other properties defined in the Server-Sent Events specification MAY be used and MUST be supported by hubs. The resource MAY be represented in a format with hypermedia capabilities such as JSON-LD [W3C.REC-json-ld11-20200716], Atom [RFC4287], XML [W3C.REC-xml-20081126] or HTML [HTML]. Web Linking [RFC8288] MAY be used to indicate the IRI of the resource sent in the event. When using Atom, XML, or HTML as the serialization format, the document SHOULD contain a link element with a self relation that holds the IRI of the resource. When using JSON- LD, the document SHOULD contain an @id property holding the IRI of the resource. Example: Dunglas Expires 12 February 2027 [Page 8] Internet-Draft Mercure August 2026 // The subscriber subscribes to updates // for the https://example.com/foo topic, the bar topic, // and to any topic matching the https://example.com/bar/:id URL Pattern const url = new URL('https://example.com/.well-known/mercure'); url.searchParams.append('match', 'https://example.com/foo'); url.searchParams.append('match', 'bar'); url.searchParams.append('match_urlpattern', 'https://example.com/bar/:id'); const eventSource = new EventSource(url); // The callback will be called every time an update is published eventSource.onmessage = function ({data}) { console.log(data); }; The hub MAY apply extra authorization rules not defined in this specification. See Section 6. 4. Matcher Types A topic matcher is an expression matched against topics; its matcher type determines how the expression is interpreted. This document defines two matcher types, exact and urlpattern. Hubs MUST support both. Additional matcher types can be defined by other specifications and registered in the "Mercure Topic Matcher Types" registry (see Section 12). Hubs MAY support registered additional matcher types and SHOULD advertise the complete set of matcher types they support with the mercure_matcher_types_supported metadata member (see Section 9.2). Requests and tokens using a matcher type the hub does not support are rejected as defined in Section 3 and Section 6.7: matcher evaluation determines both routing and authorization, so a matcher the hub cannot interpret must fail loudly rather than be skipped. The matcher value * is reserved as a wildcard that matches every topic. It is recognized before the matcher type is resolved, so it has this meaning regardless of matcher type and regardless of whether match_type is supplied or defaulted (see Section 6.7). As a consequence, a topic whose value is exactly * is not addressable: no matcher can select that single topic without also selecting every other. Publishing a topic whose value is exactly * is therefore rejected (see Section 5). This mirrors the reserved wildcard characters of other publish-subscribe systems. Dunglas Expires 12 February 2027 [Page 9] Internet-Draft Mercure August 2026 4.1. Exact Matching The hub MUST support exact matching. With this matcher type, the hub MUST perform an exact, case-sensitive, byte-for-byte comparison between the topic and the matcher. The hub MUST NOT resolve relative values against the hub's URL or any other base, and MUST NOT perform Unicode or IRI normalization. Note: Because comparison is performed on raw bytes, publishers and subscribers SHOULD normalize topic strings to a canonical form before publication or subscription. Recommended canonicalizations are Unicode NFC [UNICODE] and, for IRIs, IDNA-canonical hosts [RFC5891] and percent-encoding normalization [RFC3986]. Otherwise, visually identical topics will be treated as distinct, and homograph attacks (see Section 13) become possible. The matcher type name is exact. It is the default matcher type: the corresponding subscribe query parameter is the bare match (or, explicitly, match_exact), and it is the default match_type value in authorization details (see Section 6.7). 4.2. URL Pattern The hub MUST support using URL patterns [urlpattern] as matchers. URL patterns MAY be absolute (e.g., https://example.com/books/:id) or relative (e.g., /.well-known/mercure/subscriptions/ exact/:topic/:subscriber). When evaluating a relative pattern or a relative topic, the hub MUST use the hub's URL as the base URL. This allows subscribers to match relative topics published by the hub itself, such as subscription events (see Section 8.1). URL patterns are evaluated per the URL Pattern Living Standard [urlpattern]; hubs MUST NOT enable the ignoreCase option. Host components remain case-insensitive as defined by URL canonicalization [RFC3986]; all other components are case-sensitive. A topic that cannot be parsed as a URL reference against the hub's URL cannot be matched by a URL pattern: hubs MUST treat its evaluation against any URL pattern as not matching. Dunglas Expires 12 February 2027 [Page 10] Internet-Draft Mercure August 2026 The URL Pattern Living Standard compiles patterns to regular expressions internally; crafted patterns can therefore trigger catastrophic backtracking. To mitigate denial-of-service attacks by clients submitting pathological patterns, hubs MUST either use a regular expression engine that guarantees linear-time matching (such as RE2 [re2]) or enforce an implementation-defined evaluation cost or time limit. When such a limit is reached, the pattern MUST be treated as not matching and the evaluation MUST be aborted. URL patterns whose protocol component is a wildcard or capture group can match data:, javascript:, file:, and other potentially dangerous URI schemes. Topic strings are opaque identifiers within this protocol; subscribers MUST NOT dereference them as URLs without validating the scheme against an allowlist appropriate for the subscriber's environment. The matcher type name is urlpattern. The corresponding subscribe query parameter is match_urlpattern, and the corresponding match_type value in authorization details (see Section 6.7) is urlpattern. 4.3. Summary of Matcher Types +==============+==================+============+=============+ | Matcher Type | Subscribe Query | match_type | Requirement | | | Parameter | | | +==============+==================+============+=============+ | exact | match (or | exact | MUST | | | match_exact) | | | +--------------+------------------+------------+-------------+ | urlpattern | match_urlpattern | urlpattern | MUST | +--------------+------------------+------------+-------------+ Table 1 This table lists the matcher types defined by this document; the "Mercure Topic Matcher Types" registry (see Section 12) records additional registered types. 5. Publication The publisher sends updates by issuing POST HTTPS requests to the hub URL. When it receives an update, the hub dispatches it to subscribers using the established Server-Sent Events connections. The hub MAY also dispatch the update using other protocols such as WebSub [W3C.REC-websub-20180123] or ActivityPub [W3C.REC-activitypub-20180123]. Dunglas Expires 12 February 2027 [Page 11] Internet-Draft Mercure August 2026 An application MAY deliver events directly to subscribers without an external hub. In that case, the publish endpoint described in this section is not required. The request MUST be encoded using the application/x-www-form- urlencoded format [URL]. Field names and values MUST be UTF-8 [RFC3629]. The request MUST contain at least one topic field; all other fields defined below are optional: * topic (required): The identifier of an updated topic. It is RECOMMENDED to use an IRI as identifier. This field MAY appear more than once: the first occurrence is the canonical topic (the primary identifier of the updated resource) and any remaining occurrences are alternate topics (see Section 2). The hub dispatches the update to subscribers matching any one of these topics, and private-read authorization is evaluated against the set as a whole (see Section 6.6) — the audience of a private update is therefore the union of the audiences of all its topics (see Section 13.6). Each topic value MUST conform to the constraints defined in Section 2. Every topic value (canonical or alternate) MUST NOT address the reserved hub namespace. To test this, each topic MUST be resolved against the hub's URL (see Section 9) using the URL parser of [URL] — the same algorithm and canonicalization used for URL Pattern matching (see Section 4.2). A topic addresses the reserved namespace when the resolved path component equals the path of the hub's URL or begins with that path followed by / — for the default hub URL (see Section 9), /.well-known/mercure and /.well-known/mercure/... — regardless of scheme or authority. Before this comparison, the path MUST have its dot-segments removed and its percent-encoded octets that correspond to unreserved characters decoded [RFC3986]; otherwise, variants such as /.well-known/%6Dercure/... or /.well-known/ mercure/../mercure/... would bypass the check. A topic that cannot be parsed as a URL reference against the hub's URL does not address the reserved namespace (it cannot name a hub path) and is not rejected by this rule. This namespace is reserved for resources generated by the hub itself, including subscription events (see Section 8.1). Every topic value MUST NOT be exactly *, which is reserved for the wildcard matcher (see Section 4) and would otherwise not be addressable. Because both rules reject the request regardless of the presented access token, hubs MUST reject publish requests violating them, for any topic value, with a 400 "Bad Request" HTTP status code. Checking the resolved path component (rather than a leading-substring match on the raw value) prevents a publisher from forging subscription events with an absolute topic such as https://hub.example.com/.well- known/mercure/subscriptions/.... Dunglas Expires 12 February 2027 [Page 12] Internet-Draft Mercure August 2026 * data (optional): the content of the new version of this topic. The value MUST be valid UTF-8 [RFC3629]. When dispatching the update, the hub MUST serialize the value as one SSE data: field per line, splitting on CR, LF, or CRLF, per the Server-Sent Events serialization rules [HTML]. A receiver reassembles the fields joined by LF, so a value containing CR or CRLF is received with those sequences normalized to LF; publishers that require byte- exact round-tripping (for example, of encrypted payloads) SHOULD encode the value (for example, with base64) before publication. The value is opaque to the hub: publishers and subscribers MAY agree on any format. Only the hub-generated documents described in Section 8.1 have a format defined by this specification. * private (optional): if this field is present, the update MUST NOT be dispatched to subscribers not authorized to receive it. See Section 6. The presence of the field name marks the update as private regardless of its value, whether or not a value is supplied; hubs MUST NOT interpret the field's value to determine privacy. It is RECOMMENDED to set the value to on for interoperability, but it MAY contain any value, including an empty string. * id (optional): the topic's revision identifier; used as the SSE id property. The provided ID MUST NOT start with the # character, MUST NOT be the reserved value earliest (see Section 7), and MUST NOT contain control characters (C0 (U+0000–U+001F), U+007F, or C1 (U+0080–U+009F)) or Unicode format characters (general category Cf [UNICODE]) — the same constraint as topics (see Section 2), since the ID also travels in the Last-Event-ID HTTP field. The provided ID MAY be a valid IRI. If omitted, the hub MUST generate either a valid IRI [RFC3987] or a relative reference consisting of a fragment (starting with #). A UUID [RFC9562] or a DID [DID] MAY be used as the IRI; a fragment is convenient to return an offset or a sequence that is unique for this hub. A client-supplied ID SHOULD be unique within the scope of the hub: the hub treats IDs as cursors into a single, hub-wide event sequence rather than one scoped per topic (see Section 7), so a reused ID leaves ambiguous which update a subsequent Last-Event-ID refers to. The hub MAY ignore the client-supplied ID and generate its own. The hub MUST reject client-supplied IDs violating the character constraints above with a 400 HTTP status code. * type (optional): the SSE event property (a specific event type). The value MUST NOT contain control characters (C0 (U+0000–U+001F), U+007F, or C1 (U+0080–U+009F)) or Unicode format characters (general category Cf [UNICODE]); hubs MUST reject violating values with a 400 HTTP status code. The value mercure is reserved for updates the hub generates itself (see Section 8.1); hubs MUST reject a publish request whose type is mercure with a 400 HTTP status code, so that a publisher cannot forge such events. Dunglas Expires 12 February 2027 [Page 13] Internet-Draft Mercure August 2026 * retry (optional): the SSE retry property (the reconnection time). The value MUST consist solely of ASCII digits (U+0030–U+0039); hubs MUST reject violating values with a 400 HTTP status code. To allow future extensions, hubs MUST ignore fields they do not recognize. On success, the hub MUST return a 200 (OK) HTTP status code, and the response body MUST be the id generated by the hub for the update, served with the text/plain media type and the UTF-8 charset (Content- Type: text/plain; charset=utf-8). Other 2xx status codes are not appropriate: some cannot carry content at all (204, 205) [RFC9110], and 201 (Created) would misrepresent an ephemeral message as a resource retrievable at a dereferenceable URL — the id is an event cursor (see Section 7), not a Location. The publisher MUST be authorized to publish updates; see Section 6. Hubs SHOULD apply implementation-defined maximums to the size of the request body, to the length of individual fields, and to the number of topic fields per request. Requests exceeding any such limit MUST be rejected with a 413 "Content Too Large" HTTP status code. Example: POST /.well-known/mercure HTTP/1.1 Host: example.com Content-Type: application/x-www-form-urlencoded Authorization: Bearer [snip] topic=https://example.com/foo&data=the%20content HTTP/1.1 200 OK Content-Type: text/plain; charset=utf-8 urn:uuid:e1ee88e2-532a-4d6f-ba70-f0f8bd584022 6. Authorization The hub is an OAuth 2.0 protected resource [RFC6749]. To prove that they are authorized, publishers MUST present an access token to the hub (except in the closed-network deployments described in the note below), and subscribers MUST present an access token to receive updates marked as private. Hubs MAY accept unauthenticated subscribers; such subscribers receive only updates that are not marked as private. Hubs MAY instead require all subscribers to present an access token, according to their own policy. The access token MUST be a JWT [RFC7519] structured as a JWT access token [RFC9068] — in particular using the at+jwt media type — carried as a Dunglas Expires 12 February 2027 [Page 14] Internet-Draft Mercure August 2026 JWS [RFC7515] in compact serialization, and MUST be validated as described in Section 6.3. Every token, including a self-issued one, MUST carry the claims [RFC9068] requires issuers to populate (iss, exp, aud, sub, client_id, iat, and jti), so that any [RFC9068] validator can process it without Mercure-specific exceptions. The token SHOULD be short-lived, especially when the subscriber is a web browser. Access tokens MAY be issued by an OAuth 2.0 authorization server or self-issued by the publisher (for example, signed with a key shared out of band with the hub). The hub need not operate or trust an external authorization server. A self-issuing publisher acts as a local token issuer: it MUST use a stable issuer identifier (for example, its own URL) as the iss value, bound out of band to its signing key(s) in the hub's configuration (see Section 6.3). When an authorization server is used, the hub MAY advertise it through protected resource metadata (see Section 9). Different keys SHOULD be used to sign subscribers' and publishers' tokens so that compromise of one role does not entail compromise of the other. For example, a self-issued subscriber token is a JWS with the protected header {"alg": "ES256", "typ": "at+jwt"} and the following claims (see Section 6.3 for how a hub validates them): { "iss": "https://example.com", "aud": "https://hub.example.com/.well-known/mercure", "sub": "urn:uuid:bb3de268-05b0-4c65-b44e-8f9acefc29d6", "client_id": "https://example.com", "iat": 1767225300, "exp": 1767225600, "jti": "urn:uuid:e70ff8d7-59d5-4a92-b0b7-505e8f6d09fa", "authorization_details": [ { "type": "https://mercure.rocks/authorization-detail", "actions": ["subscribe"], "topics": [{"match": "https://example.com/books/:id", "match_type": "urlpattern"}] } ] } Authorization is expressed with the authorization_details claim [RFC9396]; see Section 6.4. Routing (which topics a subscriber listens to, via the query parameters of Section 3) is independent of authorization (what a token permits): the query parameters never grant access to private updates. Dunglas Expires 12 February 2027 [Page 15] Internet-Draft Mercure August 2026 Note: Hubs MAY also be deployed without requiring authorization for publication (for example, on a trusted private network). Because any client able to reach such a hub can publish at will, these deployments MUST NOT be reachable from networks containing untrusted clients. The remainder of this section assumes token-based authorization is in use for publication. 6.1. Presenting the Access Token Two mechanisms are defined to present the access token to the hub, following the OAuth 2.0 Bearer Token Usage specification [RFC6750] where applicable: * an Authorization HTTP header with the Bearer scheme [RFC6750], * a cookie (a Mercure extension for web browsers, see below). The access_token URI query parameter of [RFC6750] section 2.3 is not part of this specification: the OAuth 2.0 Security Best Current Practice [RFC9700] forbids clients from passing access tokens in the URI query string, and hubs implementing this specification do not accept it. When either mechanism is used, the connection MUST use an encryption layer such as HTTPS. Per [RFC6750], clients MUST NOT use more than one mechanism to transmit the token in a single request. [RFC6750] treats a request that nevertheless carries more than one mechanism as an invalid_request; this specification deviates from that handling in one narrow case: when an Authorization HTTP header is present, its token MUST be used and any cookie MUST be ignored rather than the request rejected. Cookies are ambient credentials — the user agent attaches them regardless of the client's choice of mechanism — so their presence alongside an explicit Authorization header is not treated as a client protocol violation. When no Authorization header is present, the cookie, if any, MUST be used. 6.1.1. Authorization HTTP Header Clients SHOULD use an Authorization HTTP header. This header MUST contain the string Bearer followed by a space character and by the access token, as defined in [RFC6750]. As with every HTTP authentication scheme, the scheme name is matched case-insensitively [RFC9110]. In a web browser, the fetch() API [FETCH] can set this header and consume the Server-Sent Events stream through the response body's readable stream [streams]; this is the RECOMMENDED mechanism when the Dunglas Expires 12 February 2027 [Page 16] Internet-Draft Mercure August 2026 token must be scoped to a single connection or browsing context (for example, several tabs each holding a different token), or when the hub and the web application do not share the same registrable domain — situations a cookie cannot accommodate. 6.1.2. Cookie Per the EventSource specification [HTML], web browsers cannot set custom HTTP headers on such connections, and the connections can only be established using the GET HTTP method. However, cookies are supported and can be included even in cross-origin requests when the CORS credentials mode is enabled through the withCredentials attribute of EventSource [HTML]. This cookie mechanism is a Mercure- specific extension to [RFC6750]; hubs that support it SHOULD advertise it in their protected resource metadata (see Section 9). If the publisher or the subscriber is a web browser, it SHOULD, whenever possible, send a cookie containing the access token when connecting to the hub. It is RECOMMENDED to name the cookie __Secure-mercure_access_token: the __Secure- name prefix [I-D.ietf-httpbis-rfc6265bis] makes user agents refuse the cookie over insecure transport while — unlike the __Host- prefix — remaining compatible with the Domain attribute used below. A different name MAY be used to prevent conflicts when several hubs share the same domain. The cookie SHOULD be set during discovery (see Section 9) to improve overall security. Consequently, if the cookie is set during discovery, the publisher and the hub MUST share the same registrable domain (eTLD+1). The Domain attribute MAY be used to allow the publisher and the hub to use different subdomains of that registrable domain. See Section 9. The cookie MUST have the Secure and HttpOnly attributes set [RFC6265]. The cookie SHOULD also have SameSite=Strict [I-D.ietf-httpbis-rfc6265bis]: because the publisher and the hub share the same registrable domain (see above), requests between them are same-site and SameSite=Strict does not impede them. SameSite=Lax MAY be used when the deployment requires the cookie on qualifying top-level navigations arriving from other sites; Lax does not release the cookie on cross-site subresource requests such as EventSource connections [I-D.ietf-httpbis-rfc6265bis], so it does not enable cross-site hub access — a genuinely cross-site deployment would require SameSite=None; Secure and remains subject to user-agent third-party-cookie policies, and SHOULD use the Authorization header via fetch() instead (see Section 6.1.1). The cookie's Path attribute SHOULD be set to the path of the hub's subscription URL. See Section 13. Dunglas Expires 12 February 2027 [Page 17] Internet-Draft Mercure August 2026 6.2. Error Responses The hub reports authorization failures using the error responses defined in [RFC6750] section 3. For the token-related failures below (missing, invalid, or insufficiently-scoped token), the error code is carried as the error attribute (auth-param) of a WWW-Authenticate: Bearer challenge, not as a response body field; every such 401 or 403 carries that header [RFC9110], and the challenge SHOULD include the resource_metadata parameter (see Section 9) per [RFC9728], not only when no token is presented. A 400 for a request that is malformed independently of the access token (for example, a missing topic field or an unknown matcher query parameter) need not carry a Bearer challenge: * If no access token is presented and the requested operation requires one (see above), the hub MUST return a 401 "Unauthorized" status code with a WWW-Authenticate: Bearer challenge and MUST NOT include an error code. The challenge SHOULD include a resource_metadata parameter pointing to the hub's protected resource metadata (see Section 9) per [RFC9728]. * If a token is presented but fails validation as defined in Section 6.3, or carries Mercure authorization details that fail to parse or validate or that exceed implementation-defined limits (see Section 6.4), the hub MUST return a 401 status code with error="invalid_token". * If a valid token does not authorize the requested operation, the hub MUST return a 403 "Forbidden" status code with error="insufficient_scope". * If the request is malformed, the hub MUST return a 400 "Bad Request" status code. When the malformed element is the access token or its presentation, the response MUST carry a WWW- Authenticate: Bearer challenge with error="invalid_request" [RFC6750]. A 400 for a request malformed independently of the access token conveys no [RFC6750] error code unless the hub chooses to include such a challenge, since these codes are defined only as challenge parameters. Returning invalid_token for every presented-token failure (rather than distinguishing a bad signature from an expired or not-yet-valid token) avoids disclosing why validation failed. For error responses that are not conveyed through the WWW- Authenticate: Bearer challenge (for example, a 400 for a request malformed independently of the access token, a 429, or the 400 for a publish targeting the reserved namespace), the hub MAY return a problem details document [RFC9457] as the response body. The OAuth error codes above remain carried in the challenge and are not duplicated in such a body. Dunglas Expires 12 February 2027 [Page 18] Internet-Draft Mercure August 2026 6.3. Token Validation Hubs MUST validate access tokens as JWT access tokens [RFC9068] and in accordance with the JSON Web Token Best Current Practices [RFC8725]. The requirements below profile those documents for hubs rather than replace them. In particular: * Hubs MUST verify that the token header typ is at+jwt, or the equivalent application/at+jwt, compared with the application/ prefix omitted and case-insensitively per [RFC7515] section 4.1.9 [RFC9068], so that tokens issued for other purposes (for example, OpenID Connect ID Tokens) are not accepted. * Hubs MUST be configured with an explicit allowlist of accepted signature algorithms and MUST reject any token whose alg is not on that allowlist. Hubs MUST NOT accept alg=none, MUST NOT derive the set of acceptable algorithms from the token, and MUST verify that alg is compatible with the key used for verification (preventing algorithm-confusion attacks). The allowlist SHOULD include at minimum EdDSA, ES256, and RS256, and SHOULD NOT include algorithms known to be cryptographically weak at the time of deployment. * Hubs MUST select the verification key from a preconfigured or pre- trusted set and MUST NOT use key material supplied by the token itself (such as the jwk, jku, or x5u header parameters). When more than one trusted key is in use — for example, separate publisher and subscriber keys or rotated keys — the kid header parameter MAY be used as a hint to choose among the trusted keys, as MAY the role of the endpoint; the token can thus influence which trusted key is tried, but never introduce a new one. Trusted keys are obtained from static configuration or from the authorization server's JWK Set [RFC7517] discovered through its metadata [RFC8414]. This specification defines no hub-specific key distribution endpoint. Each trusted key MUST be associated in the hub's configuration with the issuer identifier it belongs to — the authorization server's issuer identifier [RFC8414], or the stable identifier chosen by a self-issuing publisher. When the hub trusts key material from more than one issuer, it MUST verify the signature using only the key(s) associated with the token's iss, never a pooled set spanning issuers, so that a token signed by one trusted issuer cannot be accepted under another issuer's identity. * Hubs MUST enforce the exp claim [RFC7519], including on the first request received bearing a token, and MUST reject a token that has no exp claim ([RFC9068] requires it). Hubs MUST enforce the nbf claim if present. * Hubs MUST be configured with their resource identifier and MUST verify that it appears in the token aud claim [RFC9068]. It is RECOMMENDED that the resource identifier be the canonical URL of Dunglas Expires 12 February 2027 [Page 19] Internet-Draft Mercure August 2026 the hub (for example, https://hub.example.com/.well-known/ mercure), which gives deployments an obvious default. Per [RFC7519], aud MAY be a single string or an array of strings; the resource identifier matches when it equals that string or is a member of that array. This bounds a token to its intended hub and mitigates replay across hubs that share signing keys (see Section 13.11). Hubs MUST verify that the iss claim is present and exactly matches the issuer identifier of one of the hub's trusted issuers [RFC9068] — an authorization server (whether or not it is advertised in the hub's protected resource metadata, see Section 9) or a self-issuing publisher configured out of band. [RFC9068] requires issuers to populate the iss, exp, aud, sub, client_id, iat, and jti claims; this requirement applies to self- issuing publishers as it does to authorization servers (see Section 6), so that every token is a conforming [RFC9068] JWT access token. Hubs MUST enforce iss, exp, and aud as described above, per [RFC9068] section 4; the remaining claims are issuer obligations that hubs use when they rely on them. The sub claim identifies the subscriber and is used to derive subscription event identifiers (see Section 8.1). Failure of any of these checks MUST be reported as defined in Section 6.2. 6.4. Authorization Details Authorization is expressed with the authorization_details claim [RFC9396], a JSON array of authorization detail objects. This specification defines the authorization detail type identified by the URI https://mercure.rocks/authorization-detail, referred to in this document as a Mercure authorization detail. [RFC9396] does not establish a registry of authorization details type identifiers (it leaves their registration with authorization servers out of scope); as [RFC9396] section 2.1 recommends for an API deployed across independently operated servers, the type identifier is a collision- resistant URI under the control of this specification. Authorization servers supporting it advertise this URI in their authorization_details_types_supported metadata [RFC9396]. A Mercure authorization detail object: * MUST have a type property whose value is the string https://mercure.rocks/authorization-detail, compared byte by byte. * MUST have an actions property: a non-empty JSON array of strings (the actions field of [RFC9396]). This document defines the actions publish and subscribe; additional actions can be Dunglas Expires 12 February 2027 [Page 20] Internet-Draft Mercure August 2026 registered in the "Mercure Actions" registry (see Section 12). Hubs MUST ignore action values they do not recognize: an unrecognized action grants nothing, and its presence does not invalidate the token. This lets issuers include actions defined by future specifications without breaking deployed hubs; a detail whose actions contains no action recognized by the hub simply grants nothing. A non-string entry in actions remains a validation failure. * MUST have a topics property: a non-empty JSON array of topic matcher objects (see Section 6.7) identifying the topics the actions apply to. * MAY have a payload property (a JSON object), meaningful only for the subscribe action (see Section 6.8). A token grants an action on a topic when it carries a Mercure authorization detail whose actions includes that action and one of whose topics matches the topic. Tokens with no Mercure authorization detail grant no publish or subscribe rights. Hubs SHOULD apply implementation-defined maximums to the number of Mercure authorization details, to the number of entries in each topics array, and to the length of individual patterns. Tokens exceeding any such limit MUST be rejected as invalid tokens, with a 401 status code and error="invalid_token" (see Section 6.2). If any Mercure authorization detail fails to parse or validate (including failures specific to a matcher's match_type), the hub MUST reject the token the same way and *MUST NOT* act on the basis of the remaining entries; partial acceptance is forbidden because it would silently alter the effective authorization of the token. These are defects of the presented token, not of the request, so they are reported as invalid_token rather than invalid_request [RFC6750]. Hubs MAY also limit the number of concurrent subscriptions established under a single token and MAY reject further subscription attempts with a 429 "Too Many Requests" status code once the limit is reached. 6.5. Publishers A publisher MUST present a token that grants the publish action on every topic of the update, canonical and alternate alike: for each topic, the token MUST carry a Mercure authorization detail whose actions includes publish and one of whose topics matches that topic. If the token is not authorized for every topic of the update, the hub MUST NOT dispatch the update — even if some of its topics are allowed — and MUST return a 403 status code with error="insufficient_scope" (see Section 6.2). Dunglas Expires 12 February 2027 [Page 21] Internet-Draft Mercure August 2026 6.6. Subscribers To receive updates marked as private, a subscriber MUST present a token that grants the subscribe action on at least one topic of the update (canonical or alternate): the token MUST carry a Mercure authorization detail whose actions includes subscribe and one of whose topics matches at least one of the update's topics. If the token does not grant subscribe on any topic of the update, the hub MUST NOT deliver the update to the subscriber. Authorization is therefore evaluated against the update's topics as a whole, not against any one of them in isolation: the audience of a private update is the union of the audiences of each of its topics (see Section 13.6). The subscriber's routing matchers (query parameters) only select which topics it listens to; they never widen what it may read — the subscriber still needs a subscribe grant matching one of the update's topics to receive it. When the subscriber presented an access token, the hub MUST close the connection no later than the token's exp time, since exp is required (see Section 6.3). Since exp alone cannot revoke an already- established long-lived connection, hubs SHOULD also impose a maximum connection lifetime independent of exp and close connections that exceed it, requiring the subscriber to reconnect and re-authenticate. For example, a subscriber may listen to all books via the routing matcher match_urlpattern=https://example.com/books/:id while its token authorizes reading only specific books: { "authorization_details": [ { "type": "https://mercure.rocks/authorization-detail", "actions": ["subscribe"], "topics": [ {"match": "https://example.com/books/1", "match_type": "exact"}, {"match": "https://example.com/books/7", "match_type": "exact"} ] } ] } A private update for https://example.com/books/1 is delivered; a private update for https://example.com/books/2 is not, even though the routing matcher would select it. Dunglas Expires 12 February 2027 [Page 22] Internet-Draft Mercure August 2026 Alternate topics let a publisher grant this same kind of narrow, per- subscriber access without issuing a token scoped to every individual resource. Consider a subscriber authorized only for its own namespace, https://example.com/users/42/*, that listens to all books via match_urlpattern=https://example.com/books/:id: { "authorization_details": [ { "type": "https://mercure.rocks/authorization-detail", "actions": ["subscribe"], "topics": [ {"match": "https://example.com/users/42/*", "match_type": "urlpattern"} ] } ] } The publisher publishes a private update about https://example.com/ books/1, attaching https://example.com/users/42/books/1 as an alternate topic: POST /.well-known/mercure HTTP/1.1 Host: example.com Content-Type: application/x-www-form-urlencoded Authorization: Bearer [snip] topic=https://example.com/books/1&topic=https://example.com/users/42/books/1&private=on The subscriber's routing matcher selects the update by its canonical topic, books/1, which its token does not grant subscribe on. The token does grant subscribe on the alternate topic, so the hub delivers the update. A publisher MUST NOT attach to a private update an alternate topic matchable by an audience broader than the audience intended to read the update's content; doing so discloses the full content of the update to that broader audience (see Section 13.6). 6.7. Topic Matcher List A topic matcher object appears in the topics array of a Mercure authorization detail (see Section 6.4). It MUST be a JSON object with a match property containing the topic matcher itself, and MAY have an OPTIONAL match_type property containing the matcher type. The value of match_type is case-sensitive and MUST be the name of a matcher type supported by the hub (see Section 4); this document defines exact and urlpattern. Unlike unrecognized actions (see Section 6.4), a match_type the hub does not support MUST cause the token to be rejected: the grant cannot be evaluated, and skipping it Dunglas Expires 12 February 2027 [Page 23] Internet-Draft Mercure August 2026 would silently alter the effective authorization of the token. If no match_type key is present, the hub MUST assume the exact matcher type. A match value of * is the reserved wildcard and matches every topic regardless of match_type, including when match_type is absent (see Section 4). Any entry that is not a JSON object, or that fails to parse or validate as a topic matcher, MUST cause the token to be rejected with a 401 status code and error="invalid_token" as defined in Section 6.4. 6.8. Payloads User-defined data can be attached to a subscription and made available through the subscription API and in subscription events. See Section 8.1. A Mercure authorization detail with the subscribe action MAY carry a payload JSON object. The payload of the first subscribe authorization detail whose topics matches the subscription's own matcher (the match or match_ query parameter value) MUST be included under the payload key of the JSON object describing the subscription, both in the subscription API and in subscription events. A subscribe detail whose topics contains the * wildcard matches every subscription and can serve as a default. Matching here treats the subscription's own matcher string as if it were a topic: for example, the urlpattern matcher https://example.com/bar/:id in a subscribe detail matches the subscription created by match_urlpattern=https://example.com/bar/:id, and an exact matcher matches a subscription whose matcher string is byte-for-byte identical to it. Note: Payload selection is order-dependent; the first matching authorization detail wins. Issuers placing broad matchers before more specific entries will mask the payloads of the specific entries. Specific matchers SHOULD appear before broader ones. Privacy: Payloads are forwarded to other authorized subscribers via subscription events (see Section 8.1). Issuers MUST NOT place data in payloads that should not be visible to other subscribers authorized for the corresponding subscription events. In particular, storing data identifying the subscriber (such as a user identifier or IP address) effectively broadcasts that data to all other subscribers within the same subscription-events scope. Example access token claims carrying payloads: Dunglas Expires 12 February 2027 [Page 24] Internet-Draft Mercure August 2026 { "authorization_details": [ { "type": "https://mercure.rocks/authorization-detail", "actions": ["subscribe"], "topics": [{"match": "https://example.com/foo"}], "payload": {"custom1": "data only available for this topic"} }, { "type": "https://mercure.rocks/authorization-detail", "actions": ["subscribe"], "topics": [{"match": "https://example.com/bar/:id", "match_type": "urlpattern"}], "payload": {"custom2": "data available for matching subscriptions"} }, { "type": "https://mercure.rocks/authorization-detail", "actions": ["subscribe"], "topics": [{"match": "*"}], "payload": {"custom3": "default data for all other subscriptions"} } ] } For instance, a payload can carry coarse-grained metadata such as a tenant identifier or a display label for the subscription. Issuers MUST consider the privacy note above before including any identifier of the subscriber, since payloads are visible to other authorized subscribers via subscription events. 7. Reconnection, State Reconciliation, and Event Sourcing The protocol allows reconciliation of state after a reconnection. It can also be used to implement an event store [EventSourcing]. To allow re-establishment in case of connection loss, events dispatched by the hub MUST include an id property. The value of this property SHOULD be an IRI [RFC3987]. A UUID [RFC9562] or a DID [DID] MAY be used. Per the Server-Sent Events specification, the subscriber tries to reconnect automatically in case of connection loss. During reconnection, the subscriber MUST send the last received event ID in a Last-Event-ID HTTP request header [HTML]. Dunglas Expires 12 February 2027 [Page 25] Internet-Draft Mercure August 2026 To fetch any update dispatched between the initial resource generation by the publisher and the connection to the hub, the subscriber MUST send the event ID provided during discovery either as a Last-Event-ID header or as a last_event_id query parameter. See Section 9. EventSource implementations may not allow setting HTTP headers on the first connection (before a reconnection), and web browser implementations do not allow it. To work around this, the hub MUST also accept the last event ID in a query parameter named last_event_id. If both the Last-Event-ID HTTP header and the last_event_id query parameter are present, the HTTP header MUST take precedence. If the Last-Event-ID HTTP header or the last_event_id query parameter is present, the hub SHOULD send all events published after the one bearing this identifier to the subscriber, subject to authorization. The authorization rules defined in Section 6.6 apply to replayed events identically to live events: the hub MUST re-evaluate each candidate replayed event against the current access token before dispatching it. Events whose private flag is set and that the token does not authorize the subscriber to read (see Section 6.4) MUST NOT be dispatched, regardless of any authorization that may have applied at publication time. The reserved value earliest requests that the hub send all updates it has for the subscribed topics. The hub MAY ignore this request according to its own policy. Hub-generated identifiers are IRIs or fragments (see above) and publishers are forbidden from supplying earliest as an update ID (see Section 5), so earliest cannot collide with an event identifier. If more than one update in the hub's history shares the same ID, in violation of the recommendation in Section 5, a Last-Event-ID bearing that value MUST resolve to the earliest such update in the hub's history. The hub MUST then send all updates published after that one, including any later update carrying the same, reused ID. The hub MAY discard some events for operational reasons. When the request contains a Last-Event-ID HTTP header or a last_event_id query parameter, the hub MUST set a Mercure-Last-Event-ID field on the HTTP response. This document defines the Mercure-Last-Event-ID response field and registers it in Section 12 rather than reusing Last-Event- ID, whose registration [HTML] defines request semantics only. Dunglas Expires 12 February 2027 [Page 26] Internet-Draft Mercure August 2026 The value of this response field MUST be the identifier of the event preceding the first event sent to the subscriber, or the reserved value earliest if there is no preceding event (for example, when the hub history is empty, when the subscriber requests the earliest event, or when the requested event does not exist or has been discarded). Subscribers using the hub as an event store can use the returned identifier as a recovery anchor; subscribers that only need to detect data loss can compare it against the requested value (a different value indicates that loss may have occurred). Note: Event identifiers are cursors, and the hub exposes them to subscribers through the last-event-id attribute of the rel="mercure" Link header provided during discovery (see Section 9) and by the subscription API (see Section 8.2), and through the Mercure-Last- Event-ID response field. The field value can be the identifier of an event immediately preceding one the subscriber is not authorized to receive. A subscriber can therefore infer the existence of such an event and, when the hub uses time-ordered identifiers (e.g., UUIDv7 [RFC9562]), its approximate timing and ordering. Operators handling sensitive private updates SHOULD generate opaque, random event identifiers (e.g., UUIDv4 [RFC9562]), or expose an encrypted form of an internal ordered identifier, so that the cursor discloses nothing beyond what the subscriber already knows. The subscriber SHOULD NOT assume that no events will be lost (events may be lost, for instance, if the hub stores only a limited number of events in its history). In some cases (for example, when sending partial updates in the JSON Patch [RFC6902] format, or when using the hub as an event store), lost updates can cause data loss. To detect data loss, the subscriber MAY compare the value of the Mercure-Last-Event-ID response field with the last event ID it requested. In case of data loss, the subscriber SHOULD re-fetch the original topic. Note: Native EventSource implementations do not expose HTTP response headers. However, polyfills and Server-Sent Events clients in most programming languages do. The hub MAY also specify the reconnection time using the retry key, as defined by the Server-Sent Events format. Dunglas Expires 12 February 2027 [Page 27] Internet-Draft Mercure August 2026 8. Active Subscriptions Mercure provides a mechanism to track active subscriptions. If the hub supports this optional set of features, updates will be published when a subscription is created, or terminated, and a web API exposes the list of active subscriptions. Hubs supporting this feature SHOULD advertise it with the mercure_subscriptions metadata member (see Section 9.2). Variables are templated and expanded following [RFC6570]. 8.1. Subscription Events If the hub supports the active subscriptions feature, it MUST publish an update every time a subscription is created or terminated. The topic of these updates MUST be the path of the hub's URL followed by an expansion of /subscriptions/{match_type}/{match}/{subscriber} — for the default hub URL, /.well-known/mercure/ subscriptions/{match_type}/{match}/{subscriber} — with the following variables: * {match_type}: the topic matcher type used for this subscription. The value MUST be the matcher type name in its canonical case as defined in Section 4 (e.g., urlpattern, exact). URL path components are case-sensitive. * {match}: the topic matcher used for this subscription * {subscriber}: a unique identifier for the subscriber. Subscribers and publishers MUST NOT forge, supply, or override this value through query parameters, headers, request bodies, or any other client-controlled channel. It is RECOMMENDED that the hub generate a random identifier (for example, a UUID [RFC9562]) for each connection. The hub MAY instead derive the identifier from information it has cryptographically validated, but the derivation MUST yield an identifier unique per connection: the pair formed by the token's issuer and its sub claim (after validation per Section 6.3) is not sufficient on its own, because one access token can be used on several concurrent connections (for example, two browser tabs) whose subscription event topics would then collide (see Section 13.5). A derivation MUST also incorporate the issuer: sub alone is unique only within one issuer, and two trusted issuers can assign the same value to different subscribers. Hub-generated random identifiers have a privacy advantage: they do not disclose the sub value to the other subscribers authorized for subscription events. Distinct subscribers MUST receive distinct identifiers. A single subscriber holding several active subscriptions through one connection reuses the same identifier across them. Dunglas Expires 12 February 2027 [Page 28] Internet-Draft Mercure August 2026 Note: Because strings containing reserved characters (e.g., URIs, URL Patterns, and URI Templates) can be used for the {match} and {subscriber} variables, per [RFC6570] the value of each variable MUST be percent-encoded exactly once during expansion, encoding the raw matcher or subscriber string as a whole (any % characters it already contains are themselves encoded). Hubs MUST NOT double-encode an already-encoded value. {subscriber} SHOULD be an IRI [RFC3987]. A UUID [RFC9562] or a DID [DID] MAY also be used. The content of the update MUST be a JSON [RFC8259] document containing at least the following properties: * id: the identifier of this update; MUST be the same value as the subscription update's topic. * type: the fixed value subscription. * match_type: the topic matcher type used for this subscription. The value is case-sensitive and MUST be the matcher type name in its canonical case as defined in Section 4. * match: the topic matcher used for this subscription. * subscriber: the identifier of the subscriber. It SHOULD be an IRI. * active: true when the subscription is active, false when it is terminated. * payload (optional): the content of the payload field associated with this subscription in the subscriber's access token (see Section 6.8). The document MAY contain other properties. To restrict subscription events to authorized subscribers, the subscription update MUST be marked as private. The hub MUST dispatch subscription events with the update type field — the SSE event property (see Section 5) — set to the reserved value mercure. A subscriber receiving several topics through a single connection can then distinguish subscription events from application updates without inspecting the payload (for example, with addEventListener("mercure", ...)). Publishers cannot produce updates carrying this event type (see Section 5), so a subscriber can trust that an event of this type was generated by the hub. This SSE event value is distinct from the JSON type property above, which identifies the kind of document (subscription here, subscriptions for a collection, see Section 8.2). Example: Dunglas Expires 12 February 2027 [Page 29] Internet-Draft Mercure August 2026 { "id": "/.well-known/mercure/subscriptions/urlpattern/https%3A%2F%2Fexample.com%2F%3Aselector/urn%3Auuid%3Abb3de268-05b0-4c65-b44e-8f9acefc29d6", "type": "subscription", "match_type": "urlpattern", "match": "https://example.com/:selector", "subscriber": "urn:uuid:bb3de268-05b0-4c65-b44e-8f9acefc29d6", "active": true, "payload": {"foo": "bar"} } 8.2. Subscription API If the hub supports subscription events (see Section 8.1), it SHOULD also expose active subscriptions through a web API. For instance, subscribers interested in maintaining a list of active subscriptions can call the web API to retrieve them, then use subscription events (see Section 8.1) to keep the list up to date. The web API MUST expose endpoints whose paths are the path of the hub's URL followed by the patterns below (shown expanded for the default hub URL): * /.well-known/mercure/subscriptions: the collection of subscriptions. * /.well-known/mercure/subscriptions/{match_type}/{match}: the collection of subscriptions for the given topic matcher. * /.well-known/mercure/ subscriptions/{match_type}/{match}/{subscriber}: a specific subscription. To access these URLs, clients MUST be authorized according to the rules defined in Section 6. The topic to authorize is the requested URL in relative form: its absolute path (for example, /.well- known/mercure/subscriptions/{match_type}/{match}), which is the same form used for subscription event topics (see Section 8.1); any query component of the request URL is not part of the topic. The hub MUST verify that a Mercure authorization detail in the access token grants the subscribe action on this relative topic, evaluated with the matcher rules of Section 4: exact matchers are compared byte-for-byte against the relative form, while URL patterns — absolute, or relative and then resolved against the hub's URL — are evaluated against it per Section 4.2. Because subscription event topics and subscription API URLs share this canonical relative form, a single matcher covers both the events and the API resources describing the same subscriptions. The same matching applies to every endpoint shape above: the collection URL /.well-known/mercure/subscriptions, the per-matcher collection URL, and the single-subscription URL are each Dunglas Expires 12 February 2027 [Page 30] Internet-Draft Mercure August 2026 matched as a topic, so a token whose subscribe matcher selects a broader set (for example a urlpattern covering the subscriptions namespace, or the reserved *) grants access to the corresponding endpoints. If no detail grants subscribe on the requested URL, the hub MUST answer 403 as defined in Section 6. The web API MUST set the Content-Type HTTP header to application/ json. When the hub serves cross-origin subscribers, it MUST expose the Link response header to them (for example, through the Access- Control-Expose-Headers header [FETCH]) so they can read the last- event-id attribute defined below; see Section 3. URLs returning a single subscription (following the pattern /.well- known/mercure/subscriptions/{match_type}/{match}/{subscriber}) MUST expose the same document as described in Section 8.1. If the requested subscription does not exist, the hub MUST return a 404 HTTP status code. If the requested subscription is no longer active, the hub MAY either return the document with the active property set to false or return a 404 status code. Likewise, collection endpoints MAY include terminated subscriptions with active set to false or omit them. Collection endpoints MUST return JSON documents containing at least the following properties: * id: the URL used to retrieve the document. * type: the fixed value subscriptions. * subscriptions: an array of subscription documents as described in Section 8.1. In addition, every endpoint MUST carry the reconciliation cursor as a last-event-id target attribute on the rel="mercure" Link header [RFC8288], following the same mechanism as discovery (see Section 9). The value is the identifier of the last event dispatched by the hub at the time of this request (see Section 7), or earliest if no events have been dispatched yet. It SHOULD be passed back to the hub as the last_event_id query parameter (see Section 7) when subscribing to subscription events, to prevent data loss. Because the cursor is carried on the Link header, a single-subscription response body is the subscription event document of Section 8.1 without modification. Subscription events are a homogeneous stream: they are always delivered under the reserved mercure event type with a JSON body (see Section 8.1). For consistency with discovery (see Section 9), the hub SHOULD also set the type and content-type attributes on the same rel="mercure" Link header, with the values mercure and application/ json respectively. Dunglas Expires 12 February 2027 [Page 31] Internet-Draft Mercure August 2026 Active subscription collections can be large. Hubs MAY truncate or paginate collection responses according to an implementation-defined policy; each returned document MUST remain valid as described above. Pagination mechanisms are out of scope for this specification. Because data returned by this web API is volatile, clients SHOULD validate that a cached response is still fresh before using it. Examples: Dunglas Expires 12 February 2027 [Page 32] Internet-Draft Mercure August 2026 GET /.well-known/mercure/subscriptions HTTP/1.1 Host: example.com HTTP/1.1 200 OK Content-Type: application/json Link: ; rel="mercure"; last-event-id="urn:uuid:5e94c686-2c0b-4f9b-958c-92ccc3bbb4eb"; type="mercure"; content-type="application/json" ETag: "urn:uuid:5e94c686-2c0b-4f9b-958c-92ccc3bbb4eb" Cache-Control: must-revalidate { "id": "/.well-known/mercure/subscriptions", "type": "subscriptions", "subscriptions": [ { "id": "/.well-known/mercure/subscriptions/urlpattern/https%3A%2F%2Fexample.com%2F%3Aselector/urn%3Auuid%3Abb3de268-05b0-4c65-b44e-8f9acefc29d6", "type": "subscription", "match_type": "urlpattern", "match": "https://example.com/:selector", "subscriber": "urn:uuid:bb3de268-05b0-4c65-b44e-8f9acefc29d6", "active": true, "payload": {"foo": "bar"} }, { "id": "/.well-known/mercure/subscriptions/exact/https%3A%2F%2Fexample.com%2Fa-topic/urn%3Auuid%3A1e0cba4c-4bcd-44f0-ae8a-7b76f7ef1280", "type": "subscription", "match": "https://example.com/a-topic", "match_type": "exact", "subscriber": "urn:uuid:1e0cba4c-4bcd-44f0-ae8a-7b76f7ef1280", "active": true, "payload": {"baz": "bat"} }, { "id": "/.well-known/mercure/subscriptions/urlpattern/https%3A%2F%2Fexample.com%2F%3Aselector/urn%3Auuid%3Aa6c49794-5f74-4723-999c-3a7e33e51d49", "type": "subscription", "match_type": "urlpattern", "match": "https://example.com/:selector", "subscriber": "urn:uuid:a6c49794-5f74-4723-999c-3a7e33e51d49", "active": true, "payload": {"foo": "bap"} } ] } Dunglas Expires 12 February 2027 [Page 33] Internet-Draft Mercure August 2026 GET /.well-known/mercure/subscriptions/urlpattern/https%3A%2F%2Fexample.com%2F%3Aselector HTTP/1.1 Host: example.com HTTP/1.1 200 OK Content-Type: application/json Link: ; rel="mercure"; last-event-id="urn:uuid:5e94c686-2c0b-4f9b-958c-92ccc3bbb4eb"; type="mercure"; content-type="application/json" ETag: "urn:uuid:5e94c686-2c0b-4f9b-958c-92ccc3bbb4eb" Cache-Control: must-revalidate { "id": "/.well-known/mercure/subscriptions/urlpattern/https%3A%2F%2Fexample.com%2F%3Aselector", "type": "subscriptions", "subscriptions": [ { "id": "/.well-known/mercure/subscriptions/urlpattern/https%3A%2F%2Fexample.com%2F%3Aselector/urn%3Auuid%3Abb3de268-05b0-4c65-b44e-8f9acefc29d6", "type": "subscription", "match": "https://example.com/:selector", "match_type": "urlpattern", "subscriber": "urn:uuid:bb3de268-05b0-4c65-b44e-8f9acefc29d6", "active": true, "payload": {"foo": "bar"} }, { "id": "/.well-known/mercure/subscriptions/urlpattern/https%3A%2F%2Fexample.com%2F%3Aselector/urn%3Auuid%3Aa6c49794-5f74-4723-999c-3a7e33e51d49", "type": "subscription", "match": "https://example.com/:selector", "match_type": "urlpattern", "subscriber": "urn:uuid:a6c49794-5f74-4723-999c-3a7e33e51d49", "active": true, "payload": {"foo": "bap"} } ] } Dunglas Expires 12 February 2027 [Page 34] Internet-Draft Mercure August 2026 GET /.well-known/mercure/subscriptions/urlpattern/https%3A%2F%2Fexample.com%2F%3Aselector/urn%3Auuid%3Abb3de268-05b0-4c65-b44e-8f9acefc29d6 HTTP/1.1 Host: example.com HTTP/1.1 200 OK Content-Type: application/json Link: ; rel="mercure"; last-event-id="urn:uuid:5e94c686-2c0b-4f9b-958c-92ccc3bbb4eb"; type="mercure"; content-type="application/json" ETag: "urn:uuid:5e94c686-2c0b-4f9b-958c-92ccc3bbb4eb" Cache-Control: must-revalidate { "id": "/.well-known/mercure/subscriptions/urlpattern/https%3A%2F%2Fexample.com%2F%3Aselector/urn%3Auuid%3Abb3de268-05b0-4c65-b44e-8f9acefc29d6", "type": "subscription", "match": "https://example.com/:selector", "match_type": "urlpattern", "subscriber": "urn:uuid:bb3de268-05b0-4c65-b44e-8f9acefc29d6", "active": true, "payload": {"foo": "bar"} } 9. Discovery 9.1. Hub Discovery The discovery mechanism aims at identifying the URL of one or more hubs designated by the publisher. The URL of the hub SHOULD be the "well-known" [RFC8615] fixed path /.well-known/mercure, which gives publishers and subscribers a default requiring no configuration. The hub URL advertised through discovery is authoritative: it MAY be any HTTPS URL, enabling deployments behind path prefixes and several hubs sharing an origin. Protected resource metadata (see Section 9.2) is derived from the hub URL per [RFC9728] whatever its path, and the reserved namespace and subscription-event topics follow the path of the hub URL (see Section 5 and Section 8.1). Examples throughout this document assume the default hub URL. If the publisher is a server, it SHOULD advertise the URL of one or more hubs to the subscriber so that the subscriber can receive live updates. If more than one hub URL is specified, the publisher MUST notify each hub, and the subscriber MAY subscribe to one or more of them. Note: Publishers may wish to advertise and publish to more than one hub for fault tolerance and redundancy. If one hub fails to propagate an update, the others increase the likelihood of delivery to subscribers. Dunglas Expires 12 February 2027 [Page 35] Internet-Draft Mercure August 2026 The publisher SHOULD include at least one Link Header [RFC8288] with rel=mercure (a hub link header). The target URL of such links MUST be a hub implementing the Mercure protocol. Note: A compromised publisher can advertise a malicious hub URL and capture the access tokens of subscribers that connect to it. Subscribers SHOULD restrict accepted hub URLs to origins they have a basis to trust (for example, hubs sharing the publisher's registered domain) and MAY verify the hub's identity through out-of-band means before transmitting credentials. The publisher MAY provide the following target attributes in the Link Headers: * last-event-id: the identifier of the last event dispatched by the publisher at the time the resource was generated. If provided, it MUST be passed to the hub through a query parameter named last_event_id; this ensures that updates dispatched between the resource generation and the connection to the hub are not lost. See Section 7. * content-type: the content type of the updates that will be pushed by the hub. If omitted, the subscriber MUST assume that the content type matches that of the original resource. The content- type attribute is especially useful to indicate that partial updates will be pushed, in formats such as JSON Patch [RFC6902] or JSON Merge Patch [RFC7396]. Because the data field of a Server- Sent Event carries no content type of its own, this attribute lets a subscriber process the payload without content sniffing. * type: the Server-Sent Events event field value (see Section 3) that the updates pushed for this resource will carry. A subscriber using the EventSource interface [HTML] can register a listener for this type; if omitted, the subscriber MUST assume the default event type (the events delivered to the EventSource message handler). It is subject to the same character constraints as the publication type field (see Section 5). A publisher advertising its own resource MUST NOT use the reserved mercure type, which the hub generates for subscription events; the hub advertises mercure on the subscription API, where the stream consists of those events (see Section 8.2 and Section 8.1). The content-type and type attributes each describe a single, homogeneous update stream: a publisher whose updates for a resource use more than one content type, or more than one event type, MUST omit the corresponding attribute, and the subscriber then determines that value from each individual update. These attributes are hints; they do not affect routing, which is governed solely by topic matchers (see Section 3). Dunglas Expires 12 February 2027 [Page 36] Internet-Draft Mercure August 2026 All these attributes are optional. Minimal example: GET /books/foo HTTP/1.1 Host: example.com HTTP/1.1 200 OK Content-Type: application/ld+json Link: ; rel="mercure" {"@id": "/books/foo", "foo": "bar"} 9.2. Protected Resource Metadata As an OAuth 2.0 protected resource, the hub SHOULD publish OAuth 2.0 Protected Resource Metadata [RFC9728] at the path derived from its URL as defined in that specification (for the hub URL /.well-known/ mercure, the metadata is served at /.well-known/oauth-protected- resource/.well-known/mercure). Publishing the document is a SHOULD; a document that is published MUST include the resource member (required by [RFC9728]) and MAY include the others: * resource (required): the hub's resource identifier, which is the value clients MUST place in the access token aud claim (see Section 6.3). Clients MUST verify that this value equals the resource identifier they used to derive the well-known URL [RFC9728]. * authorization_servers (optional): issuer identifiers of the authorization servers that can issue tokens for the hub [RFC8414]. Omitted when tokens are self-issued. * authorization_details_types_supported: the authorization detail types the hub understands. The metadata member is defined by [RFC9728]; its values are authorization_details type identifiers per [RFC9396]. For hubs implementing this specification, the array contains https://mercure.rocks/authorization-detail (see Section 6.4). * bearer_methods_supported: the [RFC6750] token presentation methods the hub actually accepts (see Section 6.1): header [RFC9728]. The cookie mechanism is not a [RFC6750] bearer method, so it is not listed here; it is advertised by the separate mercure_cookie member below. * mercure_cookie (optional): a string, the name of the cookie in which the hub also accepts the access token (a Mercure extension to [RFC6750]; see Section 6.1.2). A client that cannot set an Authorization header (for example, a web browser using EventSource) presents the token by setting a cookie of this name. The cookie mechanism is advertised as a dedicated metadata member Dunglas Expires 12 February 2027 [Page 37] Internet-Draft Mercure August 2026 rather than a value of bearer_methods_supported, whose values are constrained to the [RFC6750] methods. This member is omitted when the hub does not offer cookie authorization. * mercure_matcher_types_supported (optional): a JSON array of strings listing the names of the topic matcher types the hub supports (see Section 4). When omitted, the supported set is exactly the two types defined by this document, exact and urlpattern; the member is only needed when the hub supports registered additional types. * mercure_subscriptions (optional): a boolean. When true, the hub implements the active subscriptions feature (see Section 8). This member is omitted when the hub does not implement it. This protocol carries no version identifier: a future incompatible revision is expected to be published as a new specification defining its own metadata members or well-known location. Hubs implementing pre-standardization revisions of this protocol (which used a topic subscribe query parameter and a bespoke token claim) do not publish protected resource metadata; clients needing to coexist with them MAY treat the absence of this metadata as a hint that the hub implements such a revision. When a request carries no access token, the hub's WWW-Authenticate: Bearer challenge SHOULD include a resource_metadata parameter pointing to this document (see Section 6.2), so that clients can discover the resource identifier and authorization server without prior configuration. 9.3. Topic Discovery The discovery mechanism MAY also be used to identify the canonical URL for the topic that subscribers are expected to use for subscriptions. The publisher MAY include one Link Header [RFC8288] with rel=self (the self link header). It SHOULD contain the canonical URL for the topic. If the link with rel=self is omitted, the current URL of the resource MAY be used as a fallback. Links embedded in HTML or XML documents as defined in the WebSub recommendation [W3C.REC-websub-20180123] MAY also be supported by subscribers. If both a header and an embedded link are provided, the header MUST be preferred. Dunglas Expires 12 February 2027 [Page 38] Internet-Draft Mercure August 2026 9.3.1. Content Negotiation For practical purposes, the rel=self URL SHOULD offer a single representation. The hub has no way to know which Media Type ([RFC6838]) or language was requested by the subscriber upon discovery, and therefore cannot select a representation on its behalf. Content negotiation can, however, be performed by returning a different rel=self URL based on the HTTP headers of the discovery request. For example, a request to /books/foo with an Accept header containing application/ld+json could return a rel=self value of /books/foo.jsonld. The example below illustrates how a topic URL can return different Link headers depending on the Accept header. GET /books/foo HTTP/1.1 Host: example.com Accept: application/ld+json HTTP/1.1 200 OK Content-Type: application/ld+json Link: ; rel="self" Link: ; rel="mercure" {"@id": "/books/foo", "foo": "bar"} GET /books/foo HTTP/1.1 Host: example.com Accept: text/html HTTP/1.1 200 OK Content-Type: text/html Link: ; rel="self" Link: ; rel="mercure" foo: bar The same technique can be used to return a different rel=self URL depending on the language requested by the Accept-Language header. Dunglas Expires 12 February 2027 [Page 39] Internet-Draft Mercure August 2026 GET /books/foo HTTP/1.1 Host: example.com Accept: application/ld+json Accept-Language: fr-FR HTTP/1.1 200 OK Content-Type: application/ld+json Content-Language: fr-FR Link: ; rel="self" Link: ; rel="mercure" {"@id": "/books/foo", "foo": "bar", "@context": {"@language": "fr-FR"}} 10. Encryption Using HTTPS does not prevent the hub from accessing the content of an update. Depending on the intended privacy of the information contained in the update, it MAY be necessary to prevent eavesdropping by the hub. To prevent the hub from reading the message content, the publisher MAY encrypt the message before sending it. The publisher SHOULD use JSON Web Encryption [RFC7516] to encrypt the content of the update. The encryption keys are shared between the publisher and the subscriber through any out-of-band mechanism, for example a JSON Web Key Set [RFC7517]; the hub is not involved in this exchange. Update encryption is considered a best practice to prevent mass surveillance, especially when the hub is managed by an external provider. Implementations SHOULD restrict JWE algorithms to those whose security properties remain acceptable at the time of deployment; in particular, RSA1_5 MUST NOT be used, due to padding oracle vulnerabilities [RFC8017]. At the time of writing, key management algorithms ECDH-ES+A256KW and RSA-OAEP-256, and content encryption algorithm A256GCM, are RECOMMENDED. JWE provides integrity per message but does not provide replay protection: a hub or an on-path attacker that captures a ciphertext can later replay it without modifying it. Publishers concerned with replay SHOULD include a freshness indicator (such as a timestamp or nonce) inside the encrypted payload and require subscribers to validate it. Dunglas Expires 12 February 2027 [Page 40] Internet-Draft Mercure August 2026 Long-lived JWE keys do not provide forward secrecy: compromise of such keys decrypts all past traffic encrypted under them. Publishers handling sensitive data SHOULD rotate JWE keys periodically and MAY use ephemeral key agreement (e.g., ECDH-ES) to bound the impact of a future key compromise. 11. Using HTTP This protocol follows the guidance of [RFC9205]. It uses standard HTTP methods, standard status codes, and registered media types, and does not overload their semantics. Clients discover a hub from rel=mercure Web Linking [RFC8288] relations (see Section 9) rather than a mandated well-known location: the fixed path /.well-known/ mercure is only a SHOULD default, and the authoritative hub URL advertised through discovery MAY be any HTTPS URL. The hub's own resources (protected resource metadata and the subscription API) hang off that authoritative URL, so the protocol adds no application semantics to a site-wide well-known space it does not own. 12. IANA Considerations 12.1. Well-Known URIs Registry The "mercure" well-known URI described in Section 9 is already registered in the "Well-Known URIs" registry. IANA is requested to update the reference of the existing registration to this document: * URI Suffix: mercure * Change Controller: IETF * Specification document(s): This specification, Section 9 * Status: permanent * Related information: N/A 12.2. Link Relation Types Registry The "mercure" link relation type described in Section 9 is already registered in the "Link Relation Types" registry. IANA is requested to update the reference of the existing registration to this document: * Relation Name: mercure * Description: The Mercure Hub to use to subscribe to updates of this resource. * Reference: This specification, Section 9 Dunglas Expires 12 February 2027 [Page 41] Internet-Draft Mercure August 2026 12.3. OAuth Protected Resource Metadata Registry The following values are to be registered in the "OAuth Protected Resource Metadata" registry established by [RFC9728]: * Metadata Name: mercure_cookie * Metadata Description: String naming the cookie in which the Mercure hub also accepts the access token * Change Controller: IETF * Specification Document(s): This specification, Section 9.2 * Metadata Name: mercure_matcher_types_supported * Metadata Description: JSON array listing the names of the Mercure topic matcher types supported by the hub * Change Controller: IETF * Specification Document(s): This specification, Section 9.2 * Metadata Name: mercure_subscriptions * Metadata Description: Boolean indicating that the Mercure hub implements the active subscriptions feature * Change Controller: IETF * Specification Document(s): This specification, Section 9.2 12.4. HTTP Field Name Registry IANA is requested to register the following entry in the "Hypertext Transfer Protocol (HTTP) Field Name Registry" defined by [RFC9110]: * Field Name: Mercure-Last-Event-ID * Status: permanent * Structured Type: N/A * Reference: This specification, Section 7 * Comments: Response field carrying the identifier of the event preceding the first event sent, or the reserved value earliest Dunglas Expires 12 February 2027 [Page 42] Internet-Draft Mercure August 2026 12.5. Mercure Topic Matcher Types Registry IANA is requested to establish a "Mercure Topic Matcher Types" registry. New registrations follow the Specification Required policy [RFC8126]. A matcher type name MUST consist of lowercase ASCII letters and digits and MUST begin with a lowercase letter. The name is case- sensitive and is used verbatim as the suffix of the match_ subscribe query parameter (see Section 3) and as the match_type value in authorization details (see Section 6.7). The designated experts verify that the defining specification states the matching semantics precisely, bounds the evaluation cost of a crafted matcher (see Section 13.7 for the kind of exposure to consider), and does not conflict with the reserved wildcard * (see Section 4). A registration provides: * Matcher Type Name: the name, subject to the syntax above. * Description: a brief description of the matching semantics. * Change Controller: "IETF" for registrations in the IETF stream, otherwise the party responsible for the registration. * Reference: the specification defining the matcher type. Note that the name syntax above admits no name equal to the reserved wildcard * (see Section 4), so no registration can shadow it. Initial registrations: +============+===================+============+================+ | Matcher | Description | Change | Reference | | Type Name | | Controller | | +============+===================+============+================+ | exact | Byte-for-byte | IETF | This | | | comparison of | | specification, | | | topic and matcher | | Section 4.1 | +------------+-------------------+------------+----------------+ | urlpattern | Matching per the | IETF | This | | | URL Pattern | | specification, | | | Living Standard | | Section 4.2 | +------------+-------------------+------------+----------------+ Table 2 Dunglas Expires 12 February 2027 [Page 43] Internet-Draft Mercure August 2026 12.6. Mercure Actions Registry IANA is requested to establish a "Mercure Actions" registry for the values of the actions property of Mercure authorization details (see Section 6.4). New registrations follow the Specification Required policy [RFC8126]. An action name MUST consist of lowercase ASCII letters and digits. Hubs ignore actions they do not recognize (see Section 6.4), so registering a new action does not require deployed hubs to change. The designated experts verify that the defining specification names an operation the hub performs on a topic, states how a token carrying the action is evaluated against the topics of its authorization detail, and does not duplicate an already registered action. A registration provides: * Action Name: the name, subject to the syntax above. * Description: a brief description of the operation the action authorizes. * Change Controller: "IETF" for registrations in the IETF stream, otherwise the party responsible for the registration. * Reference: the specification defining the action. Initial registrations: +===========+=====================+============+================+ | Action | Description | Change | Reference | | Name | | Controller | | +===========+=====================+============+================+ | publish | Send updates for | IETF | This | | | the matching topics | | specification, | | | | | Section 6.5 | +-----------+---------------------+------------+----------------+ | subscribe | Receive private | IETF | This | | | updates for the | | specification, | | | matching topics | | Section 6.6 | +-----------+---------------------+------------+----------------+ Table 3 13. Security Considerations The recommendations of the OAuth 2.0 Security Best Current Practice [RFC9700] apply to deployments of this protocol; this section highlights the considerations specific to Mercure. Dunglas Expires 12 February 2027 [Page 44] Internet-Draft Mercure August 2026 The confidentiality of the secret key(s) used to sign access tokens is a primary concern. Such keys MUST be stored securely and MUST be revoked immediately in the event of a breach. A valid access token allows any client that holds it to subscribe to or publish on the hub. Its confidentiality MUST therefore be ensured: access tokens MUST only be transmitted over secure connections. When the client is a web browser, the access token SHOULD NOT be exposed to JavaScript, to provide resilience against cross-site scripting (XSS) attacks [OWASP-XSS]. For this reason, HttpOnly cookies SHOULD be preferred as the authorization mechanism in that case. In the event of a breach, revoking access tokens before their expiration is often difficult. Short-lived tokens are therefore strongly RECOMMENDED. The hub's publishing endpoint can be targeted by cross-site request forgery (CSRF) attacks [OWASP-CSRF] when the cookie-based authorization mechanism is used. Implementations supporting that mechanism MUST mitigate such attacks: the SameSite cookie attribute recommended in Section 6.1.2 is the first line of defense, and because some deployed user agents do not enforce it, hubs SHOULD also verify that the source origin conveyed by the Origin or Referer HTTP header matches the target origin, rejecting the request when neither header is available. CSRF prevention techniques are described in depth in [OWASP-CSRF-Prevention]. Access tokens MUST NOT be passed in URLs (for example, via the access_token query parameter, which this specification does not accept; see Section 6.1). Browsers, web servers, and other software may not adequately secure URLs stored in browser history, server logs, and other data structures, and an attacker able to read those locations could steal the token [RFC9700]. 13.1. Token Validation Access tokens are validated as JWT access tokens before authorization details are evaluated (see Section 6.3). Failure to verify the typ is at+jwt, to reject alg: none, to bind alg to the key type, to enforce exp/nbf, or to verify aud enables token forgery, token type confusion (for example, accepting an ID Token), replay across contexts, and algorithm-confusion attacks. Dunglas Expires 12 February 2027 [Page 45] Internet-Draft Mercure August 2026 13.2. Server-Sent Events Field Injection Topic strings and the id, type, and retry publish fields end up on the wire as part of the Server-Sent Events framing. Values containing CR (U+000D), LF (U+000A), or NUL (U+0000) could inject arbitrary SSE fields into the stream as seen by subscribers, including forged event identifiers and event types. The character constraints in Section 2 and Section 5 prevent this injection. The data field may contain line breaks legitimately; it is not constrained the same way, so the hub MUST serialize it as one data: field per line (see Section 5) rather than emitting the raw value. A hub that writes the value without this line-splitting would let a data value containing \nevent: or \nid: inject a forged field, so this serialization is a security requirement, not only a formatting one. 13.3. Reserved Hub Namespace The path subtree of the hub URL (/.well-known/mercure/ for the default hub URL) is reserved for resources generated by the hub itself (see Section 5). A publisher with broad scope publishing under this prefix could forge subscription events (see Section 8.1) and mislead other subscribers tracking subscription lifecycle. The reserved-namespace test is applied to the topic's path component after resolution against the hub's URL and after percent-encoding normalization, not as a leading-substring match on the raw value; a substring test would let an absolute topic addressing the hub's own host (for example, https://hub.example.com/.well-known/mercure/ subscriptions/...) bypass it, and skipping normalization would let percent-encoded variants (for example, /.well-known/%6Dercure/...) do the same. The mercure SSE event type is reserved the same way. The hub sets it on the events it generates (see Section 8.1), and a subscriber may route on it (for example, with addEventListener("mercure", ...)). Because the SSE event field carries the publisher-supplied type field, a publisher could otherwise emit an update with type set to mercure on any topic and have it delivered to that listener as a forged hub event. Hubs MUST therefore reject a publish request whose type is mercure (see Section 5). Reserved-namespace enforcement bounds forgery by topic; this rule bounds it by event type, for subscribers that key on the event type rather than the topic. Dunglas Expires 12 February 2027 [Page 46] Internet-Draft Mercure August 2026 13.4. Authorization on Event Replay When a subscriber reconnects with a Last-Event-ID header or last_event_id query parameter, the same authorization rules apply to replayed events as to live events (see Section 7 and Section 6.6). A subscriber whose authorized scope has shrunk between publication and reconnection does not receive private events outside its scope at reconnection time. The Mercure-Last-Event-ID response field is a cursor, however, and MAY contain the identifier of an event the subscriber is not authorized to receive. Operators handling sensitive private updates SHOULD use opaque, random event identifiers so that this identifier discloses nothing beyond the event's existence. 13.5. Subscriber Identifier Assignment The {subscriber} identifier in subscription event topic URLs is preferably a random per-connection identifier generated by the hub, and otherwise derived from information the hub has cryptographically validated (see Section 8.1). Allowing clients to supply, suggest, or override this value through any unauthenticated channel would enable spoofing of subscription events and hijacking of subscription state belonging to other subscribers. A derivation must be unique per connection: the issuer and sub pair alone collides when one token is used on several concurrent connections holding the same matcher — the connections then share a subscription event topic, so terminating one emits an active: false event that misrepresents the state of the others, and the corresponding subscription API resource becomes ambiguous. Deriving the identifier from sub alone would additionally let subscribers of distinct issuers collide with — and thereby impersonate — one another, which is why any derivation incorporates the issuer. Identifiers derived from sub also disclose that claim's value to every subscriber authorized for the corresponding subscription events; hub-generated random identifiers avoid that disclosure. 13.6. Private Update Audience A private update is delivered to a subscriber only when the subscriber's access token grants the subscribe action on at least one of its topics (see Section 6.6 and Section 6.4). Authorization is therefore a hub-enforced check tied to the token issued for the subscriber, not a property of the subscriber's routing matchers: those only select which topics a subscriber listens to and never widen what it may read. Unauthenticated subscribers, when the hub accepts them (see Section 6), present no token and therefore never receive private updates. Dunglas Expires 12 February 2027 [Page 47] Internet-Draft Mercure August 2026 Because authorization is evaluated against the update's topics as a whole, the audience of a private update is the union of the audiences of each of its topics: attaching an alternate topic matchable by a broad audience discloses the update's full content to that audience, regardless of how narrowly the canonical topic is scoped. Publishers MUST NOT attach to a private update an alternate topic matchable by an audience broader than the audience intended to read the update's content (see Section 6.6 for a worked example). This places the per- resource confidentiality boundary in the publisher's choice of topics, in addition to the hub-enforced check against the subscriber's token: the hub verifies that the token matches some topic of the update, but does not know which topics a publisher intended as narrowing versus broadening. Issuers and publishers are jointly responsible for keeping topics and authorization details aligned with the intended access-control policy; deployments with strict per-resource confidentiality requirements should account for this when designing their topic conventions. 13.7. URL-Pattern Denial of Service URL Pattern compiles internally to a regular expression. Naive implementations on engines such as PCRE are vulnerable to catastrophic backtracking. The mitigations required in Section 4.2 — a linear-time engine (such as RE2 [re2]) or a per-evaluation cost or time limit — bound this exposure. 13.8. Payload Privacy Payloads carried in Mercure authorization details are included in subscription events and forwarded to other authorized subscribers (see Section 6.8). Within the set of subscribers authorized for the corresponding subscription events, a payload is effectively broadcast; it cannot carry private metadata about an individual subscriber. 13.9. Topic Normalization Topic strings are compared as byte sequences. Without Unicode normalization (NFC) and IDNA host canonicalization, visually identical topics may be treated as distinct, leading to undelivered updates or to spoofable topic names through homograph attacks (e.g., example.com versus a host containing Cyrillic look-alike characters). The normalization guidance in Section 4.1 addresses this. Dunglas Expires 12 February 2027 [Page 48] Internet-Draft Mercure August 2026 13.10. Resource Limits Absent limits on request and token size, malicious clients can exhaust hub resources. The implementation-defined limits described elsewhere in this document — on publish request body size, individual field length, the number of topic fields per publish request, the number of topic matcher query parameters per request, the number of Mercure authorization details and of entries in their topics arrays, individual pattern length, concurrent subscriptions per token, and concurrent connections per client and in total (see Section 3) — bound this exposure. 13.11. Hub Trust Subscribers obtain hub URLs from publishers via the discovery mechanism (see Section 9) and transmit credentials to the hub. A compromised publisher can therefore redirect subscribers to a hub of its choosing and capture those credentials. As described in Section 9, subscribers constrain the set of hub origins they connect to and can verify hub identity out of band. Scoping each token to its intended hub with the aud claim (see Section 6.3) limits the value of a captured token: a token bound to one hub's identifier cannot be replayed against another hub, even when the two share signing keys. 13.12. Protected Resource Metadata and Authorization Server Selection When the hub advertises an authorization server through protected resource metadata [RFC9728] (see Section 9), a client that is misled into using an inappropriate authorization server may expose itself to an adversary-in-the-middle. Clients SHOULD validate protected resource metadata as described in [RFC9728] and obtain it only from the deterministically derived, TLS-protected well-known location. Hubs and clients fetching metadata or key sets by URL SHOULD take precautions against server-side request forgery, such as refusing requests to internal address ranges. 13.13. Bearer Tokens and Sender Constraint The access token is a bearer credential: any party that obtains it can act within its scope until it expires. Short-lived tokens (see above) limit the exposure window but do not prevent use of a token during its lifetime. Deployments protecting high-value operations MAY additionally sender-constrain tokens, for example with DPoP [RFC9449] or mutual-TLS-bound tokens, so that a captured token is unusable without the corresponding proof-of-possession key. Dunglas Expires 12 February 2027 [Page 49] Internet-Draft Mercure August 2026 13.14. Publish Request Replay A captured publish request carrying a bearer access token can be replayed by an on-path attacker, causing the same update to be dispatched again. For most deployments re-dispatching an identical update is harmless. Deployments for which it is not SHOULD include a freshness indicator in the update (for example, checking the unique id recommended in Section 5 against previously seen values, or a timestamp) and reject duplicates. 13.15. JWE Algorithms and Replay JWE-protected updates are subject to algorithm-selection pitfalls and to replay. The algorithm restrictions and freshness guidance in Section 10 address these. 14. Privacy Considerations The general privacy guidance of [RFC6973] applies. The following considerations are specific to this protocol: * Subscription events and the subscription API expose presence information: which subscriber identifiers hold which subscriptions, and when those subscriptions are created and terminated. Hubs restrict this information to authorized subscribers (see Section 8.1); token issuers SHOULD NOT grant subscribe on the subscriptions namespace more broadly than the tracking use case requires. * Payloads embedded in access tokens are broadcast to every subscriber authorized for the corresponding subscription events (see Section 6.8 and Section 13.8). * Topic identifiers appear in URLs (subscription query parameters and subscription event topics) and are therefore visible to the hub operator and to any infrastructure that logs URLs. Sensitive information SHOULD NOT be encoded in topic strings. * The hub operator observes connection metadata — client addresses, connection times, topic matchers, and update traffic patterns — even when update contents are encrypted. Update encryption (see Section 10) bounds what a curious or compromised hub learns to this metadata. * Event identifiers act as cursors that can reveal the existence and approximate timing of updates a subscriber is not authorized to read; see Section 13.4. 15. Implementation Status [RFC Editor Note: Please remove this entire section prior to publication as an RFC.] Dunglas Expires 12 February 2027 [Page 50] Internet-Draft Mercure August 2026 This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft, and is based on a proposal described in [RFC7942]. The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs. Please note that the listing of any individual implementation here does not imply endorsement by the IETF. Furthermore, no effort has been spent to verify the information presented here that was supplied by IETF contributors. This is not intended as, and must not be construed to be, a catalog of available implementations or their features. Readers are advised to note that other implementations may exist. According to RFC 7942, "this will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. It is up to the individual working groups to use this information as they see fit." Note: entries reporting compatibility with revision 5 of this draft predate the OAuth 2.0 authorization model and the topic matcher types defined by this revision; they interoperate only with hubs implementing those earlier revisions. 15.1. Mercure.rocks Hub Organization responsible for the implementation: Dunglas Services SAS Implementation Name and Details: Mercure.rocks, available at https://mercure.rocks (https://mercure.rocks) Brief Description: This is the reference implementation of the Mercure hub. It is written in Go and is optimized for performance. Level of Maturity: Widely used. Coverage: All the features of the protocol. Version compatibility: Dunglas Expires 12 February 2027 [Page 51] Internet-Draft Mercure August 2026 The implementation follows the latest draft. Licensing: All code is covered under the GNU Affero Public License version 3 or later. Implementation Experience: Used in production. Contact Information: Kévin Dunglas, contact@mercure.rocks (mailto:contact@mercure.rocks) https://mercure.rocks (https://mercure.rocks) Interoperability: Reported compatible with all major browsers and server-side tools. 15.2. Freddie Implementation Name and Details: Freddie, https://github.com/bpolaszek/freddie (https://github.com/bpolaszek/freddie) Brief Description: Freddie is a PHP implementation of the Mercure Hub Specification. Level of Maturity: Stable. Coverage: All the features of the protocol except the subscription events. Version compatibility: The implementation follows the latest draft. Licensing: All code is covered under the GNU General Public License v3.0. Contact Information: Dunglas Expires 12 February 2027 [Page 52] Internet-Draft Mercure August 2026 https://github.com/bpolaszek/freddie (https://github.com/bpolaszek/ freddie) Interoperability: Reported compatible with all major browsers and server-side tools. 15.3. Ilshidur/node-mercure Implementation Name and Details: Ilshidur/node-mercure, https://github.com/Ilshidur/node-mercure (https://github.com/Ilshidur/node-mercure) Brief Description: Hub and Publisher implemented in Node. Level of Maturity: Beta, not suitable for production. Coverage: All the features of the protocol except the subscription events. Version compatibility: The implementation currently follows the revision 5 of the draft. Licensing: All code is covered under the GNU Public License version 3 or later. Contact Information: https://github.com/Ilshidur/node-mercure (https://github.com/Ilshidur/node-mercure) Interoperability: Reported compatible with all major browsers and server-side tools. 15.4. Symfony Implementation Name and Details: Dunglas Expires 12 February 2027 [Page 53] Internet-Draft Mercure August 2026 Symfony Mercure Component, available at https://symfony.com/doc/current/components/mercure.html (https://symfony.com/doc/current/components/mercure.html) Brief Description: This is a publisher library written in PHP. It also provides support for Mercure in the Symfony web framework. Level of Maturity: Widely used. Coverage: All the publisher features of the protocol. Version compatibility: The implementation follows the latest draft. Licensing: All code is covered under the MIT license. Implementation Experience: Used in production. Contact Information: https://symfony.com (https://symfony.com) Interoperability: Reported compatible with the Mercure.rocks Hub. 15.5. API Platform Implementation Name and Details: API Platform, available at https://api-platform.com/docs/core/ mercure/ (https://api-platform.com/docs/core/mercure/) Brief Description: Dunglas Expires 12 February 2027 [Page 54] Internet-Draft Mercure August 2026 The API Platform framework lets developers create async APIs implementing the Mercure protocol and generate clients for these APIs. Level of Maturity: Widely used. Coverage: All the publisher and consumer features of the protocol. Version compatibility: The implementation follows the latest draft. Licensing: All code is covered under the MIT license. Implementation Experience: Used in production. Contact Information: https://api-platform.com (https://api-platform.com) Interoperability: Reported compatible with the reference implementation of the Mercure Hub. 15.6. Laravel Mercure Broadcaster Implementation Name and Details: Laravel Mercure Broadcaster, available at https://github.com/mvanduijker/laravel-mercure-broadcaster (https://github.com/mvanduijker/laravel-mercure-broadcaster) Brief Description: Laravel broadcaster for Mercure. Use the Mercure protocol as transport for Laravel Broadcast. Level of Maturity: Dunglas Expires 12 February 2027 [Page 55] Internet-Draft Mercure August 2026 Production Coverage: All the publisher features of the protocol. Version compatibility: The implementation currently follows the revision 5 of the draft. An open Pull Request adds support for the latest version of the draft. Licensing: All code is covered under the MIT license. Implementation Experience: Used in production. Contact Information: https://github.com/mvanduijker/laravel-mercure-broadcaster (https://github.com/mvanduijker/laravel-mercure-broadcaster) Interoperability: Reported compatible with the reference implementation of the Mercure Hub. 15.7. dart_mercure Implementation Name and Details: dart_mercure, available at https://github.com/wallforfry/dart_mercure (https://github.com/wallforfry/dart_mercure) Brief Description: Publisher and Subscriber library for Dart / Flutter. Level of Maturity: Stable Coverage: All the publisher and subscriber features of the protocol. Dunglas Expires 12 February 2027 [Page 56] Internet-Draft Mercure August 2026 Version compatibility: The implementation follows the latest draft. Licensing: All code is covered under the BSD 2-Clause "Simplified" License. Contact Information: https://github.com/wallforfry/dart_mercure (https://github.com/wallforfry/dart_mercure) Interoperability: Reported compatible with the reference implementation of the Mercure Hub. 15.8. pymercure Implementation Name and Details: pymercure, available at https://github.com/vitorluis/python-mercure (https://github.com/vitorluis/python-mercure) Brief Description: Publisher and Subscriber library for Python. Level of Maturity: Alpha Coverage: All the publisher and subscriber features of the protocol. Version compatibility: The implementation currently follows the revision 5 of the draft. An open Pull Request adds support for the latest version of the draft. Licensing: All code is covered under the BSD 2-Clause "Simplified" License. Contact Information: Dunglas Expires 12 February 2027 [Page 57] Internet-Draft Mercure August 2026 https://github.com/vitorluis/python-mercure (https://github.com/vitorluis/python-mercure) Interoperability: Reported compatible with the reference implementation of the Mercure Hub. 15.9. Amphp Mercure Publisher Implementation Name and Details: Amphp Mercure Publisher, available at https://github.com/eislambey/ amp-mercure-publisher (https://github.com/eislambey/amp-mercure- publisher) Brief Description: Async Mercure publisher based on Amphp. Level of Maturity: Stable Coverage: All the publisher features of the protocol. Version compatibility: The implementation currently follows the revision 5 of the draft. An open Pull Request adds support for the latest version of the draft. Licensing: All code is covered under the MIT license. Contact Information: https://github.com/eislambey/amp-mercure-publisher (https://github.com/eislambey/amp-mercure-publisher) Interoperability: Reported compatible with the reference implementation of the Mercure Hub. Dunglas Expires 12 February 2027 [Page 58] Internet-Draft Mercure August 2026 15.10. Java Library for Mercure Implementation Name and Details: Java Library for Mercure, available at https://github.com/vitorluis/ java-mercure (https://github.com/vitorluis/java-mercure) Brief Description: Java library to publish messages to a Mercure Hub! Level of Maturity: Alpha Coverage: All the publisher features of the protocol. Version compatibility: The implementation currently follows the revision 5 of the draft. An open Pull Request adds support for the latest version of the draft. Licensing: All code is covered under the MIT license. Contact Information: https://github.com/vitorluis/java-mercure (https://github.com/vitorluis/java-mercure) Interoperability: Reported compatible with the reference implementation of the Mercure Hub. 15.11. Yii 2 Mercure behavior Implementation Name and Details: Yii 2 Mercure behavior, available at https://github.com/bizley/ mercure-behavior (https://github.com/bizley/mercure-behavior) Brief Description: Yii 2 behavior to automatically publish updates to a Mercure hub. Dunglas Expires 12 February 2027 [Page 59] Internet-Draft Mercure August 2026 Level of Maturity: Stable Coverage: All the publisher features of the protocol. Version compatibility: The implementation currently follows the revision 5 of the draft. Licensing: All code is covered under the Apache License 2.0. Contact Information: https://github.com/bizley/mercure-behavior (https://github.com/bizley/mercure-behavior) Interoperability: Reported compatible with the reference implementation of the Mercure Hub. 15.12. GitHub Action for Mercure Implementation Name and Details: GitHub Action for Mercure, available at https://github.com/marketplace/actions/github-action-for-mercure (https://github.com/marketplace/actions/github-action-for-mercure) Brief Description: Send a Mercure update when a GitHub event occurs. Level of Maturity: Stable Coverage: All the publisher features of the protocol. Version compatibility: Dunglas Expires 12 February 2027 [Page 60] Internet-Draft Mercure August 2026 The implementation currently follows the latest version of the draft. Licensing: All code is covered under the GNU Public License version 3 or later. Contact Information: https://github.com/Ilshidur/action-mercure (https://github.com/Ilshidur/action-mercure) Interoperability: Reported compatible with the reference implementation of the Mercure Hub. 15.13. Other Implementations Other implementations can be found on GitHub: https://github.com/topics/mercure (https://github.com/topics/mercure) 16. Acknowledgements Parts of this specification, especially Section 9 have been adapted from the WebSub recommendation [W3C.REC-websub-20180123]. The editor wishes to thank all the authors of this specification. 17. References 17.1. Normative References [FETCH] The Web Hypertext Application Technology Working Group (WHATWG), "Fetch Living Standard (Review Draft, June 2026)", June 2026, . [HTML] The Web Hypertext Application Technology Working Group (WHATWG), "HTML Living Standard (Review Draft, January 2026)", January 2026, . [I-D.ietf-httpbis-rfc6265bis] Bingler, S., West, M., and J. Wilander, "Cookies: HTTP State Management Mechanism", Work in Progress, Internet- Draft, draft-ietf-httpbis-rfc6265bis-22, 1 December 2025, . Dunglas Expires 12 February 2027 [Page 61] Internet-Draft Mercure August 2026 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 2003, . [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, . [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, January 2005, . [RFC5891] Klensin, J., "Internationalized Domain Names in Applications (IDNA): Protocol", RFC 5891, DOI 10.17487/RFC5891, August 2010, . [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, DOI 10.17487/RFC6265, April 2011, . [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, DOI 10.17487/RFC6570, March 2012, . [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012, . [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, . [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/RFC6750, October 2012, . Dunglas Expires 12 February 2027 [Page 62] Internet-Draft Mercure August 2026 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, January 2013, . [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2015, . [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", RFC 7516, DOI 10.17487/RFC7516, May 2015, . [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, May 2015, . [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, . [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, . [RFC8288] Nottingham, M., "Web Linking", RFC 8288, DOI 10.17487/RFC8288, October 2017, . [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, June 2018, . [RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, . Dunglas Expires 12 February 2027 [Page 63] Internet-Draft Mercure August 2026 [RFC8725] Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best Current Practices", BCP 225, RFC 8725, DOI 10.17487/RFC8725, February 2020, . [RFC9068] Bertocci, V., "JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens", RFC 9068, DOI 10.17487/RFC9068, October 2021, . [RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, . [RFC9396] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 Rich Authorization Requests", RFC 9396, DOI 10.17487/RFC9396, May 2023, . [RFC9700] Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, "Best Current Practice for OAuth 2.0 Security", BCP 240, RFC 9700, DOI 10.17487/RFC9700, January 2025, . [RFC9728] Jones, M.B., Hunt, P., and A. Parecki, "OAuth 2.0 Protected Resource Metadata", RFC 9728, DOI 10.17487/RFC9728, April 2025, . [UNICODE] The Unicode Consortium, "The Unicode Standard, Version 17.0.0", September 2025, . [URL] The Web Hypertext Application Technology Working Group (WHATWG), "URL Living Standard (Review Draft, February 2026)", February 2026, . [urlpattern] The Web Hypertext Application Technology Working Group (WHATWG), "URL Pattern Living Standard (Review Draft, September 2025)", September 2025, . 17.2. Informative References Dunglas Expires 12 February 2027 [Page 64] Internet-Draft Mercure August 2026 [DID] World Wide Web Consortium (W3C), "Decentralized Identifiers (DIDs) v1.0", 2022, . [EventSourcing] Fowler, M., "Event Sourcing", December 2005, . [OWASP-CSRF] OWASP Foundation, "Cross Site Request Forgery (CSRF)", 2024, . [OWASP-CSRF-Prevention] OWASP Foundation, "Cross-Site Request Forgery Prevention Cheat Sheet", 2024, . [OWASP-XSS] OWASP Foundation, "Cross Site Scripting (XSS)", 2024, . [RFC10008] Reschke, J., Snell, J.M., and M. Bishop, "The HTTP QUERY Method", RFC 10008, DOI 10.17487/RFC10008, June 2026, . [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom Syndication Format", RFC 4287, DOI 10.17487/RFC4287, December 2005, . [RFC6902] Bryan, P., Ed. and M. Nottingham, Ed., "JavaScript Object Notation (JSON) Patch", RFC 6902, DOI 10.17487/RFC6902, April 2013, . [RFC6973] Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., Morris, J., Hansen, M., and R. Smith, "Privacy Considerations for Internet Protocols", RFC 6973, DOI 10.17487/RFC6973, July 2013, . [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, DOI 10.17487/RFC7396, October 2014, . [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running Code: The Implementation Status Section", BCP 205, RFC 7942, DOI 10.17487/RFC7942, July 2016, . Dunglas Expires 12 February 2027 [Page 65] Internet-Draft Mercure August 2026 [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch, "PKCS #1: RSA Cryptography Specifications Version 2.2", RFC 8017, DOI 10.17487/RFC8017, November 2016, . [RFC9205] Nottingham, M., "Building Protocols with HTTP", BCP 56, RFC 9205, DOI 10.17487/RFC9205, June 2022, . [RFC9449] Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., Jones, M., and D. Waite, "OAuth 2.0 Demonstrating Proof of Possession (DPoP)", RFC 9449, DOI 10.17487/RFC9449, September 2023, . [RFC9457] Nottingham, M., Wilde, E., and S. Dalal, "Problem Details for HTTP APIs", RFC 9457, DOI 10.17487/RFC9457, July 2023, . [RFC9562] Davis, K., Peabody, B., and P. Leach, "Universally Unique IDentifiers (UUIDs)", RFC 9562, DOI 10.17487/RFC9562, May 2024, . [W3C.REC-activitypub-20180123] Lemmer-Webber, C., Ed. and J. Tallon, Ed., "ActivityPub", W3C REC REC-activitypub-20180123, W3C REC-activitypub- 20180123, 23 January 2018, . [W3C.REC-json-ld11-20200716] Longley, D., Ed., Kellogg, G., Ed., and P. Champin, Ed., "JSON-LD 1.1", W3C REC REC-json-ld11-20200716, W3C REC- json-ld11-20200716, 16 July 2020, . [W3C.REC-websub-20180123] Parecki, A., Ed. and J. Genestoux, Ed., "WebSub", W3C REC REC-websub-20180123, W3C REC-websub-20180123, 23 January 2018, . [W3C.REC-xml-20081126] Maler, E., Ed., Yergeau, F., Ed., Paoli, J., Ed., Sperberg-McQueen, M., Ed., and T. Bray, Ed., "Extensible Markup Language (XML) 1.0 (Fifth Edition)", W3C REC REC- xml-20081126, W3C REC-xml-20081126, 26 November 2008, . Dunglas Expires 12 February 2027 [Page 66] Internet-Draft Mercure August 2026 [re2] Google, "RE2: a principled approach to regular expression matching", 2024, . [streams] The Web Hypertext Application Technology Working Group (WHATWG), "Streams Living Standard", 2026, . [xhr] The Web Hypertext Application Technology Working Group (WHATWG), "XMLHttpRequest Living Standard (Review Draft, August 2025)", August 2025, . Appendix A. Changes from Pre-Standardization Deployments This appendix is non-normative. It summarizes the wire-level differences between this specification and the pre-standardization revisions of Mercure still deployed in the wild, to help implementers migrate. It complements the version-detection note in Section 9: a hub that publishes no protected resource metadata (see Section 9.2) likely implements one of these earlier revisions. Dunglas Expires 12 February 2027 [Page 67] Internet-Draft Mercure August 2026 +=============+====================+================================+ |Aspect |Pre-standardization | This specification | +=============+====================+================================+ |Authorization|mercure JWT claim | RFC 9396 | |grant |with publish and | authorization_details entry | | |subscribe arrays of | with type | | |topic selectors | https://mercure.rocks/ | | | | authorization-detail, an | | | | actions array (publish, | | | | subscribe), and a topics | | | | array (see Section 6.4) | +-------------+--------------------+--------------------------------+ |Token type |any signed JWT | JWT access token with typ | | | | at+jwt (see Section 6.3) | +-------------+--------------------+--------------------------------+ |Topic |raw topic selectors | exact and urlpattern matcher | |matching |passed as topic | types selected with the | | |query parameters | match/match_ | | | | query parameters or the | | | | match_type member (see | | | | Section 4) | +-------------+--------------------+--------------------------------+ |Reconnection |lastEventID | last_event_id (see Section 7) | |query | | | |parameter | | | +-------------+--------------------+--------------------------------+ |Reconnection |Last-Event-ID | Mercure-Last-Event-ID (see | |response | | Section 7) | |field | | | +-------------+--------------------+--------------------------------+ |Authorization|mercureAuthorization| __Secure-mercure_access_token | |cookie | | (see Section 6.1.2) | +-------------+--------------------+--------------------------------+ |Token in the |authorization query | not accepted; Authorization | |URL |parameter | header or cookie (see | | | | Section 6.1) | +-------------+--------------------+--------------------------------+ Table 4 Author's Address Kévin Dunglas (editor) Les-Tilleuls.coop 82 rue Winston Churchill 59160 Lille France Email: kevin@les-tilleuls.coop Dunglas Expires 12 February 2027 [Page 68]