Relay–Push Gateway Protocol

Meshline Protocol 1.0

This protocol defines how push gateway addresses are obtained, and the message format, authentication, and interaction rules for relays sending message notifications to gateways. Its capability identifier is push.notify.v1.

Gateway declarations and capabilities

A device declares its complete callback address in push_gateway in its DeviceCertificate. Omission means no gateway is declared. The address can propagate with the device certificate. The address and certificate MUST NOT contain identifiers used by a push platform to locate a device, callback secrets, or platform credentials.

A relay declares support for the push capability defined by this protocol through push.notify.v1.

Address sources and updates

Relays obtain push gateway addresses from verified device certificates. Gateway declarations are distinguished by (account, device_id) within the current network. When adopting a device certificate, update the declaration from its push_gateway; if the field is omitted, clear the previous declaration. Closing a connection or expiring a session does not clear the declaration.

When a relay confirms that a device is no longer authorized by its account, it clears the device's gateway declaration. After authorization is restored, the relay MUST obtain and verify a device certificate again. Sending notifications follows Send target validation.

Gateway address

push_gateway MUST be a complete absolute HTTPS URL with a valid host: it starts with https://, is at most 512 UTF-8 bytes, allows a query, and MUST NOT contain whitespace, a fragment, userinfo, or a backslash. Even an empty fragment is forbidden.

This complete address is the receiving endpoint; a relay MUST NOT append a fixed path. push_gateway in device certificates and notifications MUST retain the original address. A nonconforming address MUST NOT be accepted after adding a missing path, removing parts, changing case, or otherwise rewriting it. Target address binding compares the complete strings character for character, not by URL equivalence.

Address format validation does not depend on DNS availability at the time. Each actual connection MUST also satisfy Callback connection security.

PushNotification

Each notification targets only one recipient device. Field representations and unknown properties follow the General conventions.

Message information in a notification MUST be consistent with the original message and its record. A gateway MUST NOT reject a notification solely because it does not recognize message_type.

Omit sender_nickname if the nickname is unavailable or empty.

A notification MUST NOT contain the original message envelope, ciphertext, key boxes, device certificates, or attachment content, including through unknown properties. Its use is limited to alerts, display, and navigation. Recipients MUST NOT use it to advance synchronization cursors, mark messages as read, or establish the validity of message content.

Signing and authentication

Signing excludes only root relay_signature, retaining all other fields and unknown properties, and follows Network-bound JSON inputs and Relay account signatures.

The gateway MUST obtain its expected network and complete public callback address from trusted configuration, rather than establishing expected values from a request or untrusted forwarding headers. Before accepting a notification, it MUST:

1. Validate the JSON representation, object type, fields, size, and identifier formats. Account network magic MUST match the expected network.
2. Compare network with the expected network and push_gateway with the configured public receiving address character for character; construct the signing input from the expected network.
3. Verify the public-key/relay_id binding and notification signature. Relay public keys and signature representations follow the corresponding field constraints of RelayDescriptor.
4. Confirm through the Registry of the expected network that the relay is registered as active.
5. Complete Gateway acceptance and deduplication.

The gateway MUST complete these checks before returning a successful response to a notification request, including duplicate requests.

The gateway authenticates the relay sending the notification under these rules; the recipient device is not required to authorize each relay separately.

HTTP callbacks

Send target validation

Before each notification send, check the current gateway address under Address sources and updates. If push_gateway in an already issued notification differs from the current address, the notification MUST NOT be sent.

Before sending, the relay MUST confirm that the original message permits push, the target device is currently authorized by its account, and the device has access to the information involved in the notification. Account messages using MessageEnvelope and group messages using GroupMessageEnvelope permit push only when notify is true.

The device's current authorization is confirmed by its home relay: if this relay is responsible for the account, read the current local authoritative device state; otherwise, use a verified result from device.status. Cache reuse and invalidation follow that method and the Cache invalidation and follow-up query rules. Without an available verified authorization result, the notification MUST NOT be sent.

Gateway confirmation

The relay sends an HTTPS OPTIONS request with no request body to the complete push_gateway address, following Callback connection security. An endpoint supporting this protocol returns:

HTTP/1.1 204 No Content
Meshline-Push: push.notify.v1

Confirmation succeeds only upon receiving 204 No Content with the Meshline-Push response header value equal to push.notify.v1. The header name is case-insensitive; the value is case-sensitive.

The relay MAY reuse a confirmation result, but the current gateway address MUST match the complete URL of the confirmation request character for character. An address change requires confirmation again. Notifications MUST NOT be sent to an address that has not been successfully confirmed.

Request

The relay sends an HTTPS POST to the complete push_gateway address, using Content-Type: application/json and the complete UTF-8-encoded PushNotification, without a JSON-RPC wrapper. The request body is limited to 4 KiB (4,096 bytes), including whitespace and unknown properties.

Successful responses

When a notification request succeeds, the gateway returns 200 OK, Content-Type: application/json, and a result object:

{"status":"accepted"}

All three statuses stop relay retries. accepted does not mean that the platform has accepted the notification, or that the device has received, displayed, or read it.

A response MAY include extension properties that do not change these meanings; the receiver ignores them. Only 200 OK combined with a result object conforming to this section constitutes a successful response. A 2xx response that does not meet this condition is treated as an unknown outcome.

Errors and retries

Error bodies MAY provide diagnostic information. After accepting a notification, the gateway MUST NOT return a retryable HTTP error because subsequent platform processing fails.

A relay choosing to retry MAY retry connection failures, unknown outcomes, 408, 429, and 5xx; other 4xx responses terminate this notification. 429 MAY provide Retry-After as a nonnegative integer number of seconds. A retry MUST respect that waiting period; an invalid value MUST NOT be treated as zero.

Retries MUST reuse the complete signed notification unchanged. Send target validation MUST also be performed before a retry.

Gateway acceptance and deduplication

Deduplication requirements apply within a single run of the same gateway. Within the same network, recipient account, and device, the gateway uses (from, message_id) to identify duplicate notifications. After validation, the gateway MUST NOT accept or skip the same notification more than once within the deduplication validity period. Subsequent and concurrent duplicate requests MUST return duplicate and MUST NOT trigger additional processing, even if the original notification has not finished processing.

Callback connection security

Whenever establishing a connection, the relay MUST verify that the final actual destination is a publicly routable unicast IP. It MUST reject the local host's addresses and all loopback, private, link-local, multicast, unspecified, or other nonpublic addresses, including IPv4-mapped IPv6 addresses whose corresponding IPv4 address is restricted.

DNS resolution checks MUST remain consistent with the actual connection destination. A relay MUST NOT check one address and then resolve again or connect to another address without checking it. It MUST verify that the TLS certificate is bound to the original URL host and MUST NOT disable certificate verification. It MUST NOT follow any 3xx response or redirect a request to an address supplied in one. A request MUST NOT be sent if these checks fail.

Compatibility and conformance requirements

Implementations conforming to this module MUST pass the Push notification test vectors and, under the Conformance testing boundaries, cover:

• Gateway declarations: certificate field omission, addition, modification, and removal; dual-signature coverage, device ID stability, unknown-property retention, address format and size; obtaining addresses from device certificates, and declaration handling on certificate updates, session termination, and device invalidation.
• Notification messages and authentication: field constraints, signature and identity forgery, cross-network isolation, and target address binding.
• Send targets: message push conditions, current device authorization and information access permissions, target validation after an address change, and prohibition of sending when authorization results are unavailable.
• Gateway confirmation: an empty request body, response status and capability header, complete URL binding, confirmation after an address change, and prohibition of sending notifications when confirmation fails.
• HTTP interactions: the three successful results, error responses, optional retries, waiting periods, unchanged retries, concurrent deduplication, deduplication scope, and rejection when unavailable.
• Callback connection security: restricted IPs, DNS destination changes, TLS host verification, and redirects.