The Mercure Protocol

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.¶

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

This table lists the matcher types defined by this document; the "Mercure Topic Matcher Types" registry (see Section 12) records additional registered types.¶

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.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.¶

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 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 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).¶

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.¶

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 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_<matcher-type> 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:¶

{
    "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.¶

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.¶

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:¶

{
   "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 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.¶

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:¶

GET /.well-known/mercure/subscriptions HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://example.com/.well-known/mercure>; 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"}
      }
   ]
}

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: <https://example.com/.well-known/mercure>; 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"}
      }
   ]
}

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: <https://example.com/.well-known/mercure>; 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.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.¶

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).¶

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: <https://example.com/.well-known/mercure>; 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 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.¶

GET /books/foo HTTP/1.1
Host: example.com
Accept: application/ld+json

HTTP/1.1 200 OK
Content-Type: application/ld+json
Link: </books/foo.jsonld>; rel="self"
Link: <https://example.com/.well-known/mercure>; 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: </books/foo.html>; rel="self"
Link: <https://example.com/.well-known/mercure>; rel="mercure"

<!doctype html>
<link rel="self" href="/books/foo.html">
<link rel="mercure" href="https://example.com/.well-known/mercure">
<title>foo: bar</title>

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: </books/foo-fr-FR.jsonld>; rel="self"
Link: <https://example.com/.well-known/mercure>; rel="mercure"

{"@id": "/books/foo", "foo": "bar", "@context": {"@language": "fr-FR"}}

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¶

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¶

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_<matcher-type> 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:¶

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:¶

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.¶

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.¶

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.¶

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.¶

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.¶

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.¶

15.1. Mercure.rocks Hub

Organization responsible for the implementation:¶

Dunglas Services SAS¶

Implementation Name and Details:¶

Mercure.rocks, available at 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:¶

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 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¶

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:¶

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¶

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¶

Interoperability:¶

Reported compatible with all major browsers and server-side tools.¶

15.4. Symfony

Implementation Name and Details:¶

Symfony Mercure Component, available at 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¶

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/¶

Brief Description:¶

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¶

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¶

Brief Description:¶

Laravel broadcaster for Mercure. Use the Mercure protocol as transport for Laravel Broadcast.¶

Level of Maturity:¶

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¶

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¶

Brief Description:¶

Publisher and Subscriber library for Dart / Flutter.¶

Level of Maturity:¶

Stable¶

Coverage:¶

All the publisher and subscriber features of the protocol.¶

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¶

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¶

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:¶

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¶

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¶

Interoperability:¶

Reported compatible with the reference implementation of the Mercure Hub.¶

15.10. Java Library for Mercure

Implementation Name and Details:¶

Java Library for Mercure, available at 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¶

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¶

Brief Description:¶

Yii 2 behavior to automatically publish updates to a Mercure hub.¶

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¶

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¶

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:¶

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¶

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¶